Подключение оплаты по платежной ссылке

Общая информация

Схема работы

1. Пользователь нажимает на кнопку оплаты в приложении.

2. Пользователь переходит на экран платежной формы Яндекс Пэй, где отображается информация о заказе и способы оплаты:

   • список банковских карт пользователя;
   • варианты оплаты через систему быстрых платежей (СБП).

3. Пользователь выбирает способ оплаты и нажимает на кнопку подтверждения заказа.

4. Сервис Яндекс Пэй проводит платеж и возвращает результат выполнения операции.

Полная оплата

Оплата в сплит

Требования к подключению

Поддерживаемая версия: Android 7.0 и выше.

Шаг 1. Подготовка идентификаторов

Перед началом интеграции получите идентификаторы, которые понадобятся при подключении SDK:

• Merchant ID — идентификатор магазина в личном кабинете Яндекс Пэй. Узнать Merchant ID
• Android package name (applicationId) — уникальный идентификатор Android-приложения. Подробнее об Application ID
• SHA256 Fingerprints — криптографический хэш сертификата Android-приложения. Получить SHA256 Fingerprints
• Client ID (YANDEX_CLIENT_ID) — идентификатор приложения в сервисе Яндекс OAuth. Получить Client ID

1.1 Получение SHA256 Fingerprints

Получите значение хеша SHA256 Fingerprints с помощью утилиты keytool:

keytool -list -v -alias <your-key-name> -keystore <path-to-production-keystore>

После ввода команды значение хеша отобразится в блоке Certificate fingerprints: SHA256.

1.2 Получение Client ID

Чтобы получить Client ID, зарегистрируйте приложение в сервисе Яндекс OAuth — это нужно, чтобы покупатели при оплате через Яндекс Пэй могли авторизоваться с помощью своего Яндекс ID.

1. Перейдите в сервис Яндекс OAuth, нажмите кнопку Создать, выберите вариант Для авторизации пользователей и перейдите к созданию.

   

2. В поле Название вашего сервиса укажите название, которое будет отображаться пользователям на экране авторизации, и загрузите иконку приложения.

   

3. В разделе Платформы приложений выберите Android-приложение и укажите его параметры:

   • Android package name — уникальное имя приложения из applicationId в конфигурационном файле проекта;
   • SHA256 Fingerprints — значение хеша SHA256. Все буквы в хеше должны быть заглавными.

   

4. Добавьте доступ к Яндекс Пэй: в разделе Права доступа к данным пользователей в поле Название доступа укажите и выберите Оплата через Yandex Pay.

   Примечание

   Доступ Управление заказами Yandex Pay Checkout не требуется. Если он у вас добавлен, удалите его.

   

5. Нажмите кнопку Продолжить → Всё верно, создать приложение и скопируйте значение поля Client ID.

   

6. В разделе Настройки личного кабинета Яндекс Пэй нажмите Добавить Client ID и укажите значение Client ID.

   

   Там же в разделе Настройки нажмите Добавить приложения, выберите нужный Client ID, платформу приложения и укажите SHA256 и Android package name в полях SHA256 Fingerprint и Android package name соответственно.

   

Шаг 2. Настройка проекта

Подготовьте Android-проект к работе с Яндекс Пэй SDK: подключите полученный Client ID и инициализируйте Firebase и AppMetrica.

2.1 Подключение Client ID

Укажите полученный Client ID в сборочном скрипте build.gradle в manifestPlaceholders в качестве значения YANDEX_CLIENT_ID:

android {
  defaultConfig {
    manifestPlaceholders = [
      // Подставьте ваш Client ID
      YANDEX_CLIENT_ID: "12345678901234567890",
    ]
  }
}

2.2 Инициализация FirebaseApp

Мобильный SDK использует службы AppMetrica, которые необходимы для стабильной работы SDK. Этот шаг позволяет исправить проблемы совместимости сервисов Firebase и сервисов метрик.

При использовании Firebase вместе с Яндекс Пэй SDK необходимо вызывать FirebaseApp.initialize(context) во всех процессах приложения.

Если вы используете AppMetrica в своем приложении, активировать YandexMetrica необходимо после инициализации Firebase.

// Не забудьте объявить MyApplication в AndroidManifest.xml в блоке <application/>, используя android:name
class MyApplication: Application() {

    override fun onCreate() {
        // Инициализируется в каждом процессе приложения
        FirebaseApp.initializeApp(this)
    }
}

Шаг 4. Подключение Yandex Pay SDK

Укажите зависимость в ваших сборочных скриптах build.gradle:

dependencies {
    implementation 'com.yandex.pay:pay:2.9.0'
}

Шаг 5. Получение объекта платежной сессии

При помощи функции getYandexPaymentSession получите объект платежной сессии:

private val yaPayConfig = YPayConfig(
  merchantData = MerchantData(
      id = MerchantId("merchantId"), // Merchant ID магазина из личного кабинета Яндекс Пэй
      name = MerchantName("merchantName"), // Наименование продавца (магазина)
      url = MerchantUrl("https://merchant.com/"), // URL сайта продавца (магазина)
  ),
  environment = YPayApiEnvironment.PROD, // Необходимое окружение: SANDBOX — для тестовой среды, PROD — для боевой среды
)

private val paymentSessionKey = PaymentSessionKey(
  generateSessionKey()
)

private val paymentSession: PaymentSession = YPay.getYandexPaymentSession(
  context = this,
  config = yaPayConfig,
  sessionKey = paymentSessionKey  // Необязательный в реализации на Kotlin
)

private YPayConfig getPayConfig() {
  return new YPayConfig(
      new MerchantData(
          new MerchantId("merchantId"), // Merchant ID магазина из личного кабинета Яндекс Пэй
          new MerchantName("merchantName"), // Наименование продавца (магазина)
          new MerchantUrl("https://merchant.com/") // URL сайта продавца (магазина)
      ),
      YPayApiEnvironment.PROD // Необходимое окружение: SANDBOX — для тестовой среды, PROD — для боевой среды
  );
}

private PaymentSessionKey getPaymentSessionKey() {
  return new PaymentSessionKey(
      generateSessionKey()
  );
}

private PaymentSession getPaymentSession() {
  return YPay.INSTANCE.getYandexPaymentSession(
      this,
      getPaymentSessionKey(),
      getPayConfig()
  );
}

При получении PaymentSession необходимо передать:

• Context — контекст приложения или Activity;
• PaymentSessionKey — ключ платежной сессии;
• YPayConfig — данные конфигурации Yandex Pay SDK.

При создании YPayConfig необходимо передать:

• merchantData — данные продавца:

  • id — Merchant ID магазина из личного кабинета Яндекс Пэй;
  • name — наименование продавца (магазина);
  • url — URL сайта продавца (магазина).

• environment — среда выполнения Yandex Pay SDK: PROD или SANDBOX.

Шаг 6. (опционально) Размещение кнопки Яндекс Пэй на экране

Подробнее о кнопке Яндекс Пэй читайте в разделе Кнопки оплаты Яндекс Пэй.

1. Разместите кнопку в вашей верстке:

   <androidx.constraintlayout.widget.ConstraintLayout
       xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:app="http://schemas.android.com/apk/res-auto"
       xmlns:tools="http://schemas.android.com/tools">
   
       <com.yandex.pay.YPayButton
           android:id="@+id/y_pay_button"
           android:layout_width="300dp"
           android:layout_height="54dp"
           android:layout_marginTop="4dp"
           app:ypay_color_scheme="by_theme"
           app:ypay_corner_radius="4dp" />
   

   При создании кнопки можно передать значения атрибутов:

   • ypay_color_scheme — позволяет определить цветовую гамму кнопки. Возможные значения:

     • by_theme — цветовая гамма адаптируется в зависимости от темы в системе;
     • light — всегда светлая цветовая гамма;
     • dark — всегда темная цветовая гамма.

   • ypay_corner_radius — позволяет определить закругление кнопки, значение передается в dp.

2. При инициализации view компонентов свяжите текущий объект сессии с кнопкой при помощи объекта класса PaymentSession и его функции bindTo.

   Передайте дополнительно SessionListenerArgs, в котором укажите платежные способы для пользователя.

   Kotlin

   Java

   fun initViews() {
       paymentSession.bindTo(yPayButton, SessionListenerArgs(listOf(PaymentMethodType.CARD,PaymentMethodType.SPLIT)))
   }
   

   void initViews() {
       getPaymentSession().bindTo(yPayButton);
   }
   

Шаг 7. Инициализация контракта запуска Яндекс Пэй

При инициализации контракта добавьте callback с получением результата YPayResult:

private val yandexPayLauncher = YPayLauncher(this) { result: YPayResult ->
    when (result) {
        is YPayResult.Success -> showToast("Finished with success")
        is YPayResult.Cancelled -> showToast("Finished with cancelled event")
        is YPayResult.Failure -> showToast("Finished with domain error")
    }
}

private final YPayLauncher launcher = new YPayLauncher(this, yPayResult -> {
    if (yPayResult instanceof YPayResult.Success) {
        handleResult("Finished with success");
    } else if (yPayResult instanceof YPayResult.Cancelled) {
        handleResult("Finished with cancelled event");
    } else if (yPayResult instanceof YPayResult.Failure) {
        handleResult("Finished with domain error");
    }
});

В случае неуспешной оплаты, дополнительно возвращается код ошибки errorMsg:

Шаг 8. Формирование данных для запуска Яндекс Пэй

Перед запуском Яндекс Пэй сформируйте платежные данные при помощи класса PaymentData.PaymentUrlFlowData, а также данные платежной сессии. Сформируйте YPayContractParams на их основе.

val paymentData = PaymentData.PaymentUrlFlowData(
    // Ссылка на оплату заказа, полученная из Pay API
    paymentUrl = "payment-url"
)

val params = YPayContractParams(
    paymentSession = paymentSession,
    paymentData = paymentData,
)

final PaymentData paymentData = new PaymentData.PaymentUrlFlowData(
    // Ссылка на оплату заказа, полученная из Pay API
    "payment-url"
);

// параметры запуска Яндекс Пэй
final YPayContractParams params = new YPayContractParams(
    getPaymentSession(),
    paymentData
);

Шаг 9. Запуск сервиса Яндекс Пэй

Запуск через кнопку Яндекс Пэй

Передайте ранее созданный лаунчер в кнопку при помощи функции setOnClickListener и определите логику его запуска в lambda-выражении. При запуске лаунчера передайте в него параметры YPayContractParams:

yPayButton.setOnClickListener(yandexPayLauncher) { launcher ->
    val params = YPayContractParams(...)
    launcher.launch(params)
}

yPayButton.setOnClickListener(yandexPayLauncher, launcher -> {
    YPayContractParams params = new YPayContractParams(...);
    launcher.launch(params);
});

Запуск без кнопки

Запустите сервис с помощью лаунчера, передав параметры запуска YPayContractParams:

val params = YPayContractParams(...)
yandexPayLauncher.launch(params)

final YPayContractParams params = new YPayContractParams(...);
yandexPayLauncher.launch(params);

Шаг 10. Обработка результата

После запуска сервиса Яндекс Пэй, SDK выберет оптимальную стратегию и запустит платежную форму, в рамках которой будет проведена оплата. Результат будет получен с помощью контракта запуска YPayLauncher.

Настройка для устройств с версией ниже 7.0

Владельцы устройств с версиями Android 7.0 (API 24 lvl) и выше могут пользоваться SDK Яндекс Пэй без ограничений. Для устройств с версиями ниже 7.0 возможности ограничены:

• нет официальной поддержки;
• ограничен функционал SDK;
• потребуется дополнительная настройка окружения по шагам ниже.

1. Подключите зависимость SDK в build.gradle вашего проекта:

   dependencies{
       ...
       implementation "com.yandex.pay:*pay/other*:*version*"
       ...
   }
   

2. Синхронизируйте проект и попробуйте собрать его. У вас должна появиться ошибка слияния манифестов:

   Manifest merger failed : uses-sdk:minSdkVersion *Your min version* cannot be smaller than version 24 declared in library
   

3. Откройте AndroidManifest.xml файл того модуля, в котором вы подключаете зависимость и перечислите все библиотеки, попадающие в эту ошибку.

   Пример:

   <manifest xmlns:tools="http://schemas.android.com/tools">
       <uses-sdk tools:overrideLibrary="com.yandex.pay, ...* other libraries *... ,com.yandex.pay.base"/>
   </manifest>
   

4. Проверьте доступность поддержки SDK через объект YPay и инициализируйте все необходимые компоненты после проверки:

   if (YPay.isSupported){
       // init Yandex pay
   } else {
       // do some other logic
   }
   

   Важно

   Проверяйте доступность YPay.isSupported при каждом обращении к SDK Яндекс Пэй.