YooKassa Payments SDK for Flutter

Version Version Version

Библиотека позволяет встроить прием платежей в мобильные приложения на Flutter и работает как дополнение к API ЮKassa.

Плагин построен поверх двух нативных мобильных SDK ЮKassa:

Платформа Нативный SDK Версия Документация
Android yookassa-android-sdk 8.6.0 README · Changelog
iOS YooKassaPayments 12.0.2 README · Changelog · Migration guide

Платёжный интерфейс (форма оплаты, токенизация, подтверждение платежа) реализован в нативных SDK. Этот плагин предоставляет Dart API для запуска этих сценариев из Flutter-приложения.

Подробная документация об интеграции, настройке способов оплаты, подтверждении платежей, сертификатах Минцифры и другие детали — в README нативных SDK (ссылки в таблице выше). Эта документация описывает только специфику Flutter.

Подключение зависимостей

В файл pubspec.yaml добавьте зависимость и запустите pub get:

dependencies:
  flutter:
    sdk: flutter
  yookassa_payments_flutter: ^version

или используйте команду flutter pub add yookassa_payments_flutter.

Управление версиями нативных SDK

Вы можете самостоятельно указать версию нативного SDK.

Для Android в файле build.gradle укажите переменную yookassa_version:

ext {
    yookassa_version = 'x.x.x'
}

Для iOS в файле Podfile укажите переменную YOOKASSA_VERSION:

ENV['YOOKASSA_VERSION'] = 'x.x.x'

Быстрая интеграция

  1. Создайте TokenizationModuleInputData (понадобится ключ для клиентских приложений из личного кабинета ЮKassa). В этой модели передаются параметры платежа (валюта и сумма) и параметры платежной формы, которые увидит пользователь при оплате (способы оплаты, название магазина и описание заказа).
var clientApplicationKey = "<Ключ для клиентских приложений>";
var amount = Amount(value: "999.9", currency: Currency.rub);
var shopId = "<Идентификатор магазина в ЮKassa>";
var tokenizationModuleInputData =
    TokenizationModuleInputData(
        clientApplicationKey: clientApplicationKey,
        title: "Космические объекты",
        subtitle: "Комета повышенной яркости, период обращения — 112 лет",
        amount: amount,
        shopId: shopId,
        savePaymentMethod: SavePaymentMethod.on);
  1. Запустите процесс токенизации и получите токен в TokenizationResult:
var result = await YookassaPaymentsFlutter.tokenization(tokenizationModuleInputData);
if (result is SuccessTokenizationResult) {
    var token = result.token;
    var paymentMethodType = result.paymentMethodType;
}

  1. Отправьте токен в вашу систему и создайте платеж по API ЮKassa, передав токен в параметре payment_token. Способ подтверждения при создании платежа зависит от способа оплаты, который выбрал пользователь — он приходит вместе с токеном в paymentMethodType.

  2. При необходимости подтвердите платеж (см. Подтверждение платежа).

Важное ограничение

Методы tokenization, confirmation и bankCardRepeat — асинхронные (async), результат оплаты возвращается через Future после закрытия нативного экрана (токенизация, 3DS, SberPay, СБП и т.д.).

Если ОС Android убьёт процесс приложения, пока открыт нативный экран оплаты (например, пользователь ушёл в банк-приложение для 3DS-подтверждения и система освободила память), то после восстановления процесса результат оплаты не будет доставлен.

Рекомендации

  1. Сохраняйте параметры запущенного платежа (TokenizationModuleInputData / confirmation URL) в персистентное состояние приложения (SharedPreferences, Hive и т.п.) перед запуском SDK.
  2. После рестарта проверяйте, был ли платёж в процессе, и при необходимости перезапускайте поток через tokenization / confirmation / bankCardRepeat.
  3. Подтверждайте результат на бэкенде по paymentId через YooKassa API — это надёжнее, чем полагаться исключительно на клиентский колбэк.

Доступные способы оплаты

  • PaymentMethod.yooMoney — ЮMoney (платежи из кошелька или привязанной картой)
  • PaymentMethod.bankCard — банковская карта
  • PaymentMethod.sberbank — SberPay
  • PaymentMethod.sbp — СБП
  • PaymentMethod.alfaPay — Alfa Pay

Настройка способов оплаты

Способы оплаты конфигурируются при создании TokenizationModuleInputData в параметре tokenizationSettings (по умолчанию используются все доступные способы):

var settings = TokenizationSettings(
    PaymentMethodTypes([
        PaymentMethod.bankCard,
        PaymentMethod.sberbank,
        PaymentMethod.yooMoney,
        PaymentMethod.sbp,
        PaymentMethod.alfaPay,
    ]),
);

var tokenizationModuleInputData = TokenizationModuleInputData(
    ...,
    tokenizationSettings: settings,
);

Для некоторых способов оплаты нужна дополнительная платформенная настройка. Она выполняется так же, как описано в документации нативных SDK:

Способ оплаты Что нужно Документация
ЮMoney Получить client id центра авторизации и передать его в moneyAuthClientId iOS · Android (раздел «Запуск токенизации кошельком ЮMoney»)
SberPay iOS: запросить у поддержки (b2b_support@yoomoney.ru) уникальную URL-scheme, зарегистрированную в системе Сбера, передать её в applicationScheme и зарегистрировать в Info.plist. Android: указать собственную схему приложения (deeplink) в build.gradle — resValue "string", "ym_app_scheme" iOS · Android (раздел «SberPay»)
СБП iOS: передать схему приложения в applicationScheme и зарегистрировать её в Info.plist. Android: указать собственную схему приложения (deeplink) в build.gradle — resValue "string", "ym_app_scheme" iOS · Android (раздел «СБП»)
Alfa Pay Подтверждение происходит на странице Альфа-Банка, открываемой SDK iOS · Android (раздел «Alfa Pay»)
Банковская карта Для 3-D Secure на Android — корневой сертификат Russian Trusted Root CA, на iOS — обработка сертификатов Минцифры iOS · Android (раздел «Подтверждение платежа → 3DSecure»)

Настройка deeplink на iOS

Для возврата в приложение после оплаты/авторизации через внешние приложения (SberPay, ЮMoney, СБП) добавьте в AppDelegate вашего Flutter-приложения обработку ссылок через YooKassa (API версии 12.x):

import YooKassaPayments

override func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    return YooKassa.handleOpen(url: url)
}

Схему приложения передавайте в TokenizationModuleInputData в параметре applicationScheme и зарегистрируйте её в Info.plist (подробнее — в README iOS SDK).

На Android параметр applicationScheme не используется: схему приложения задайте в build.gradle через resValue "string", "ym_app_scheme" (подробнее — в README Android SDK).

Подтверждение платежа

Если ваш сервер сообщил о необходимости подтверждения платежа (платёж пришёл со статусом pending), вызовите метод confirmation, передав confirmationUrl, полученный от API ЮKassa при создании платежа:

await YookassaPaymentsFlutter.confirmation(
    confirmationUrl,
    result.paymentMethodType,
    clientApplicationKey,
    shopId,
);

Завершение confirmation() не гарантирует, что пользователь фактически подтвердил платеж (он мог его пропустить). После возврата управления запросите статус платежа через YooKassa API.

Подробнее о сценариях подтверждения (3-D Secure, SberPay, СБП, Alfa Pay) — в документации iOS SDK и Android SDK (раздел «Подтверждение платежа»).

Платёж привязанной к магазину картой с дозапросом CVC/CVV

  1. Создайте SavedBankCardModuleInputData:
var savedBankCardModuleInputData = SavedBankCardModuleInputData(
    clientApplicationKey: clientApplicationKey,
    title: "Космические объекты",
    subtitle: "Комета повышенной яркости, период обращения — 112 лет",
    amount: amount,
    savePaymentMethod: SavePaymentMethod.on,
    shopId: shopId,
    paymentMethodId: paymentMethodId,
);
  1. Запустите процесс и получите токен в TokenizationResult:
var result = await YookassaPaymentsFlutter.bankCardRepeat(savedBankCardModuleInputData);

Описание публичных параметров

TokenizationModuleInputData

Обязательные:

Параметр Тип Описание
clientApplicationKey String Ключ для клиентских приложений из личного кабинета ЮKassa
title String Название магазина в форме оплаты
subtitle String Описание заказа в форме оплаты
amount Amount Объект, содержащий сумму заказа и валюту
shopId String Идентификатор магазина в ЮKassa (раздел Организации)
savePaymentMethod SavePaymentMethod Объект, описывающий логику того, будет ли платеж рекуррентным

Необязательные:

Параметр Тип Описание
gatewayId String По умолчанию null. Используется, если у вас несколько платежных шлюзов с разными идентификаторами.
tokenizationSettings TokenizationSettings По умолчанию используются все доступные способы оплаты. Отвечает за настройку токенизации.
testModeSettings TestModeSettings По умолчанию null. Настройки тестового режима.
returnUrl String По умолчанию null. URL страницы (только https), на которую надо вернуться после прохождения 3-D Secure. Необходим только при кастомной реализации 3-D Secure. Если вы используете confirmation(), не задавайте этот параметр.
isLoggingEnabled bool По умолчанию false. Включает логирование сетевых запросов.
userPhoneNumber String По умолчанию null. Телефонный номер пользователя в формате +7XXXXXXXXXX.
customizationSettings CustomizationSettings Цвет основных элементов, кнопки, переключатели, поля ввода.
moneyAuthClientId String По умолчанию null. Идентификатор для центра авторизации в системе ЮMoney (см. таблицу способов оплаты).
applicationScheme String По умолчанию null. Схема для возврата в приложение после оплаты/авторизации через внешние приложения.
customerId String По умолчанию null. Уникальный идентификатор покупателя в вашей системе (до 200 символов). Используется для привязки банковской карты. Убедитесь, что customerId относится к пользователю, который хочет совершить покупку.
lang String По умолчанию null. Фиксированный язык, независимый от системной настройки. Возможные значения: "ru", "en". Поддерживается только на iOS.
googlePayParameters GooglePayParameters По умолчанию поддерживает mastercard и visa. Настройки для платежей через Google Pay (Android).

SavedBankCardModuleInputData

Обязательные:

Параметр Тип Описание
clientApplicationKey String Ключ для клиентских приложений из личного кабинета ЮKassa
title String Название магазина в форме оплаты
subtitle String Описание заказа в форме оплаты
paymentMethodId String Идентификатор сохраненного способа оплаты
amount Amount Объект, содержащий сумму заказа и валюту
shopId String Идентификатор магазина в ЮKassa (раздел Организации)
savePaymentMethod SavePaymentMethod Объект, описывающий логику того, будет ли платеж рекуррентным

Необязательные:

Параметр Тип Описание
gatewayId String По умолчанию null. Используется, если у вас несколько платежных шлюзов с разными идентификаторами.
testModeSettings TestModeSettings По умолчанию null. Настройки тестового режима.
returnUrl String По умолчанию null. URL страницы (только https), на которую надо вернуться после прохождения 3-D Secure.
isLoggingEnabled bool По умолчанию false. Включает логирование сетевых запросов.
customizationSettings CustomizationSettings Цвет основных элементов, кнопки, переключатели, поля ввода.
customerId String По умолчанию null. Уникальный идентификатор покупателя в вашей системе.
lang String По умолчанию null. Фиксированный язык. Поддерживается только на iOS.

TokenizationSettings

Параметр Тип Описание
paymentMethodTypes PaymentMethodTypes По умолчанию PaymentMethodTypes.all. Способы оплаты, доступные пользователю в приложении.

TestModeSettings

Параметр Тип Описание
paymentAuthorizationPassed bool Определяет, пройдена ли платежная авторизация при оплате ЮMoney.
cardsCount int Количество привязанных карт к кошельку в ЮMoney.
charge Amount Сумма и валюта платежа.
enablePaymentError bool Определяет, будет ли платеж завершен с ошибкой.

Amount

Параметр Тип Описание
value String Сумма платежа
currency Currency Валюта платежа

Currency

Параметр Описание
Currency.rub ₽ — Российский рубль
Currency.usd $ — Американский доллар
Currency.eur € — Евро
Currency("custom") Будет отображаться переданное значение

CustomizationSettings

Параметр Тип Описание
mainScheme Color По умолчанию используется цвет Color.fromARGB(255, 0, 112, 240). Цвет основных элементов, кнопки, переключатели, поля ввода.
showYooKassaLogo bool По умолчанию true. Отвечает за отображение логотипа ЮKassa.

SavePaymentMethod

Параметр Тип Описание
SavePaymentMethod.on SavePaymentMethod Сохранить платёжный метод для проведения рекуррентных платежей. Пользователю будут доступны только способы оплаты, поддерживающие сохранение. На экране контракта будет отображено сообщение о том, что платёжный метод будет сохранён.
SavePaymentMethod.off SavePaymentMethod Не дает пользователю выбрать, сохранять способ оплаты или нет.
SavePaymentMethod.userSelects SavePaymentMethod Пользователь выбирает, сохранять платёжный метод или нет. Если метод можно сохранить, на экране контракта появится переключатель.

Логирование

Включить логирование всех сетевых запросов можно, передав isLoggingEnabled: true при создании TokenizationModuleInputData.

Тестовый режим

Тестовый режим не выполняет сетевых запросов и имитирует ответ от сервера. Подробнее — в документации iOS SDK и Android SDK (раздел «Настройка mock режима»).

var testModeSettings = TestModeSettings(true, 5, Amount(value: "999", currency: Currency.rub), false);

var tokenizationModuleInputData = TokenizationModuleInputData(
    ...,
    testModeSettings: testModeSettings);

Кастомизация интерфейса

Цвет основных элементов задается через CustomizationSettings:

var tokenizationModuleInputData = TokenizationModuleInputData(
    ...,
    customizationSettings: const CustomizationSettings(Colors.black));

Решение проблем подключения/сборки

  1. pod install завершается с ошибкой

  • Попробуйте команду pod update YooKassaPayments

  • В некоторых сложных случаях рекомендуем сбросить кэш cocoapods.

    Далее рекомендуем выполнить flutter clean, pod clean и pod deintegrate YOUR_PROJECT_NAME.xcodeproj для последующей чистой установки командой pod install

  1. При сборке получили ошибку xcode no such module '__ObjC'
  • Откройте ios проект в Xcode, выберите target Runner, перейдите в настройки Build Settings и выставьте флаг Build Libraries for Distribution в NO. Для project Runner проделайте то же самое — Project Runner -> Build Settings -> установите Build Libraries for Distribution в NO. Далее в Xcode Product -> Clean build folder.., и также очистите содержимое DerivedData

FAQ

  1. В iOS в виджете для ввода реквизитов банковской карты часть полей отображается на русском, а часть на английском языке. Есть какая-то возможность настроить работу виджета так, чтобы надписи отображались на установленном в iOS языке?

Да. Настройте правильно ключи локализации для flutter проекта. Например en и ru_RU. Подробнее описано здесь https://localizely.com/i18n-questions/flutter/why-flutter-localization-does-not-work-on-ios-platform/

Пример использования

Пример Flutter-приложения с полной интеграцией плагина — в директории example.

Лицензия

YooKassa Payments SDK доступна под лицензией MIT. Смотрите LICENSE файл для получения дополнительной информации.

Libraries

input_data/saved_card_module_input_data
input_data/tokenization_module_input_data
models/amount
models/currency
models/customization_settings
models/google_pay_parameters
models/host_parameters
models/method_save_payment
models/payment_method_types
models/test_mode_settings
models/tokenization_result
models/tokenization_settings
yookassa_payments_flutter