Миграция на Yandex Pay Kit

Это руководство поможет перейти с монолитного com.yandex.pay:pay (2.x) на новый модульный Yandex Pay Kit.

Yandex Pay Kit разбит на независимые модули — подключайте только те, которые нужны вашему приложению. Конфигурация (окружение, тема, локаль) задается один раз через единую точку входа YPay.init { … }, а сценарии подключаются через массив flow-модулей.

Что изменилось

Параметр	Android SDK 2.x (было)	Yandex Pay Kit для Android (стало)
Артефакт	`com.yandex.pay:pay`	`com.yandex.pay:pay-with-redirect` (и другие модули)
Точка входа	`com.yandex.pay.YPay`	`com.yandex.pay.facade.api.YPay`
Инициализация	—	`YPay.init(context, flows) { … }`
Manifest-placeholders	`YANDEX_CLIENT_ID`	`YANDEX_CLIENT_ID` + `YANDEX_PAY_CLIENT_ID`
Окружение	`YPayApiEnvironment.PROD` / `SANDBOX`	`YPayEnvironment.PRODUCTION` / `SANDBOX`
Локаль	`Locale.SYSTEM` / `RU` / `EN`	`YPayLocale.SYSTEM` / `RU` / `EN`
Тема экранов	`YPayThemeColorScheme.SYSTEM` / `LIGHT` / `DARK`	`YPayTheme.SYSTEM` / `LIGHT` / `DARK`
Конфиг сессии	`YPayConfig(merchantData, environment)` каждому вызову	`merchantId` — параметр `payWithRedirectFlow(...)`, остальное — глобально
Получение сессии	`YPay.getYandexPaymentSession(context, config, key)`	`YPay.payWithRedirect.getYandexPaymentSession(key)`
Платежные данные	`PaymentData.PaymentUrlFlowData(paymentUrl, …)`	`PaymentData(paymentUrl, metadata)`
Контракт лаунчера	`YPayContract` + `YPayLauncher`	`YPayLauncher`
Цветовая схема кнопки	`YPayButtonColorScheme.BY_THEME` / `LIGHT` / `DARK`	`YPayTheme.SYSTEM` / `LIGHT` / `DARK`
Тип кнопки	`YPayButtonType.PAY` / `CHECKOUT`	`YPayButtonType.PAY` (`CHECKOUT` удален)

Шаг 1. Обновление зависимостей

Монолитный артефакт com.yandex.pay:pay заменен на набор независимых flow-модулей. Подключите только те, которые нужны.

Было:

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

Стало:

dependencies {
    implementation "com.yandex.pay:pay-with-redirect:3.<MINOR>.<PATCH>"
    // другие модули при необходимости
}

Актуальную версию можно посмотреть на Maven Central. Полный список доступных модулей — в документации Yandex Pay Kit.

Manifest-placeholders

В версии 3.0 добавлен обязательный placeholder — YANDEX_PAY_CLIENT_ID. Для миграции достаточно указать в нем то же значение, что и в YANDEX_CLIENT_ID:

android {
  defaultConfig {
    manifestPlaceholders = [
      YANDEX_CLIENT_ID:     "12345678901234567890", // как и раньше
      YANDEX_PAY_CLIENT_ID: "12345678901234567890", // новый, можно тот же Client ID
    ]
  }
}

Подробнее — в документации модуля Авторизация.

Примечание

Инициализация Firebase / AppMetrica осталась без изменений — см. документацию Легаси Яндекс Пэй Шаг 2. Настройка проекта.

Шаг 2. Обновление импортов

В Yandex Pay Kit все типы распределены из единого пакета com.yandex.pay в специализированные пакеты.

Было:

import com.yandex.pay.YPa
import com.yandex.pay.YPayConfig
import com.yandex.pay.YPayApiEnvironment
import com.yandex.pay.Locale
import com.yandex.pay.MerchantData
import com.yandex.pay.MerchantId
import com.yandex.pay.MerchantName
import com.yandex.pay.MerchantUrl
import com.yandex.pay.PaymentData
import com.yandex.pay.PaymentSession
import com.yandex.pay.PaymentSessionKey
import com.yandex.pay.PaymentMethodType
import com.yandex.pay.SessionListenerArgs
import com.yandex.pay.YPayButton
import com.yandex.pay.YPayButtonColorScheme
import com.yandex.pay.YPayContract
import com.yandex.pay.YPayContractParams
import com.yandex.pay.YPayLauncher
import com.yandex.pay.YPayResult

Стало:

import com.yandex.pay.facade.api.YPay
import com.yandex.pay.configuration.YPayEnvironment
import com.yandex.pay.configuration.YPayLocale
import com.yandex.pay.configuration.YPayTheme
import com.yandex.pay.merchant.MerchantId
import com.yandex.pay.payment.PaymentData
import com.yandex.pay.payment.YPayResult
import com.yandex.pay.session.PaymentMethodType
import com.yandex.pay.withredirect.api.facade.payWithRedirectFlow
import com.yandex.pay.withredirect.api.facade.payWithRedirect
import com.yandex.pay.withredirect.api.session.PaymentSession
import com.yandex.pay.withredirect.api.session.PaymentSessionKey
import com.yandex.pay.withredirect.api.session.SessionListenerArgs
import com.yandex.pay.withredirect.api.button.YPayButton
import com.yandex.pay.withredirect.api.launcher.YPayContractParams
import com.yandex.pay.withredirect.api.launcher.YPayLauncher

Шаг 3. Инициализация SDK

В Yandex Pay Kit перед первым обращением необходимо однократно проинициализировать SDK через DSL YPay.init. Окружение, тема и локаль теперь задаются глобально, а каждый flow-модуль подключается отдельно.

Было:

YPay.theme = YPayThemeColorScheme.SYSTEM
YPay.locale = Locale.SYSTEM

Стало:

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        FirebaseApp.initializeApp(this)

        YPay.init(
            context = this,
            flows = listOf(
                payWithRedirectFlow(merchantId = "MERCHANT_ID"), // ← merchantId переехал сюда
            ),
        ) {
            environment = YPayEnvironment.PRODUCTION              // ← было YPayApiEnvironment.PROD
            theme = YPayTheme.SYSTEM                              // ← было YPayThemeColorScheme.SYSTEM
            locale = YPayLocale.SYSTEM                            // ← было Locale.SYSTEM
        }
    }
}

Важно

YPay.init нужно вызывать строго до первого обращения к YPay.payWithRedirect (обычно — в Application.onCreate). Повторный вызов init игнорируется. Если flow-модуль payWithRedirectFlow не передан в flows, вызов YPay.payWithRedirect завершится исключением.

Смена `merchantId`

В предыдущей версии SDK merchantId передавался в каждый getYandexPaymentSession через YPayConfig. В Yandex Pay Kit он зафиксирован при init — чтобы поменять его без полного clear(), используйте reinit:

YPay.payWithRedirect.reinit(merchantId = "NEW_MERCHANT_ID")

Обновление темы и локали

В Yandex Pay Kit тема и локаль меняются через DSL, а не через mutable-поля:

Было:

YPay.theme = YPayThemeColorScheme.DARK
YPay.locale = Locale.RU

Стало:

YPay.updateConfiguration {
    theme = YPayTheme.DARK
    locale = YPayLocale.RU
}

Шаг 4. Получение платежной сессии

YPay.getYandexPaymentSession больше не принимает параметры Context и YPayConfig — конфигурация задается при вызове init. Работа с сессией теперь выполняется через отдельный flow-фасад payWithRedirect.

Было:

private val yaPayConfig = YPayConfig(
    merchantData = MerchantData(
        id = MerchantId("MERCHANT_ID"),
        name = MerchantName("MERCHANT_NAME"),
        url = MerchantUrl("https://merchant.com/"),
    ),
    environment = YPayApiEnvironment.PROD,
)

private val paymentSession: PaymentSession = YPay.getYandexPaymentSession(
    context = this,
    config = yaPayConfig,
    sessionKey = PaymentSessionKey(generateSessionKey()),
)

Стало:

private val paymentSession: PaymentSession = YPay.payWithRedirect.getYandexPaymentSession(
    sessionKey = PaymentSessionKey(value = generateSessionKey()), // необязательный, по умолчанию — UUID
)

Примечание

MerchantName и MerchantUrl больше не передаются на стороне Android SDK. Достаточно merchantId в payWithRedirectFlow(...).

Удалить сессию по-прежнему можно явно:

YPay.payWithRedirect.removePaymentSession(sessionKey)

Шаг 5. Размещение кнопки оплаты

XML-разметка кнопки не изменилась — атрибуты ypay_color_scheme, ypay_corner_radius, ypay_has_outline_border остались с теми же значениями:

<com.yandex.pay.withredirect.api.button.YPayButton
    android:id="@+id/y_pay_button"
    android:layout_width="300dp"
    android:layout_height="54dp"
    app:ypay_color_scheme="by_theme"
    app:ypay_corner_radius="4dp"
/>

Важно

Полное имя класса в layout изменилось: com.yandex.pay.YPayButton → com.yandex.pay.withredirect.api.button.YPayButton.

Программное изменение цветовой схемы

Кнопка больше не использует отдельный YPayButtonColorScheme — ее цветовая схема теперь определяется единым enum YPayTheme, который используется и для тем экранов.

Было:

yPayButton.colorScheme = YPayButtonColorScheme.BY_THEME

Стало:

yPayButton.colorScheme = YPayTheme.SYSTEM  // BY_THEME → SYSTEM, LIGHT/DARK — без изменений

Тип кнопки

Тип кнопки CHECKOUT удален, доступен только PAY. Если вы использовали YPayButtonType.CHECKOUT, замените его на YPayButtonType.PAY.

Связь кнопки с сессией

Сигнатура bindTo и SessionListenerArgs сохранилась — поменялись только пакеты импортов:

// было
import com.yandex.pay.SessionListenerArgs
import com.yandex.pay.PaymentMethodType

// стало
import com.yandex.pay.withredirect.api.session.SessionListenerArgs
import com.yandex.pay.session.PaymentMethodType

paymentSession.bindTo(
    sessionListener = yPayButton,
    args = SessionListenerArgs(
        selectedPaymentMethods = listOf(PaymentMethodType.CARD, PaymentMethodType.SPLIT),
    ),
)

Шаг 6. Лаунчер контракта

Сигнатура YPayLauncher сохранилась — поменялись только пакеты импортов:

// было
import com.yandex.pay.YPayLauncher
import com.yandex.pay.YPayResult

// стало
import com.yandex.pay.withredirect.api.launcher.YPayLauncher
import com.yandex.pay.payment.YPayResult

private val yandexPayLauncher = YPayLauncher(this) { result: YPayResult ->
    when (result) {
        is YPayResult.Success -> handleSuccess(orderId = result.orderId)
        is YPayResult.Failure -> handleFailure(errorMsg = result.errorMsg)
        YPayResult.Cancelled -> handleCancelled()
    }
}

Замена `YPayContract` на `YPayLauncher`

Если вы использовали YPayContract, перейдите на YPayLauncher.

Было:

val launcher = registerForActivityResult(YPayContract(this)) { result ->
    // обработка
}

// запуск
launcher.launch(
    YPayContractParams(
        paymentSession = paymentSession,
        paymentData = paymentData,
    ),
)

Стало (запуск без кнопки):

val launcher = YPayLauncher(this) { result: YPayResult ->
    // обработка
}

launcher.launch(
    YPayContractParams(
        paymentSession = paymentSession,
        paymentData = paymentData,
    ),
)

Стало (запуск через YPayButton):

yPayButton.setOnClickListener(
    yPayLauncher = launcher,
    listener = { buttonLauncher ->
        buttonLauncher.launch(
            YPayContractParams(
                paymentSession = paymentSession,
                paymentData = paymentData,
            ),
        )
    },
)

Шаг 7. Запуск оплаты

PaymentData больше не является sealed-интерфейсом с единственным наследником PaymentUrlFlowData. Теперь это обычный data class. Удалите вложенный конструктор.

Было:

val paymentData = PaymentData.PaymentUrlFlowData(
    paymentUrl = "payment-url",
)

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

Стало:

val paymentData = PaymentData(
    paymentUrl = "payment-url",
    metadata = null,
)

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

Запуск оплаты через кнопку и напрямую без кнопки не изменился:

// через кнопку
yPayButton.setOnClickListener(yandexPayLauncher) { launcher ->
    launcher.launch(YPayContractParams(paymentSession = paymentSession, paymentData = paymentData))
}

// напрямую
yandexPayLauncher.launch(YPayContractParams(paymentSession = paymentSession, paymentData = paymentData))

Была ли статья полезна?

Первичная установка

Отладка App Link

Миграция на Yandex Pay Kit

Что изменилось

Шаг 1. Обновление зависимостей

Manifest-placeholders

Шаг 2. Обновление импортов

Шаг 3. Инициализация SDK

Смена merchantId

Обновление темы и локали

Шаг 4. Получение платежной сессии

Шаг 5. Размещение кнопки оплаты

Программное изменение цветовой схемы

Тип кнопки

Связь кнопки с сессией

Шаг 6. Лаунчер контракта

Замена YPayContract на YPayLauncher

Шаг 7. Запуск оплаты

Была ли статья полезна?

Смена `merchantId`

Замена `YPayContract` на `YPayLauncher`