YooKassa Payments SDK for Flutter #

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'

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

Создайте 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);

Запустите процесс токенизации и получите токен в TokenizationResult:

var result = await YookassaPaymentsFlutter.tokenization(tokenizationModuleInputData);
if (result is SuccessTokenizationResult) {
    var token = result.token;
    var paymentMethodType = result.paymentMethodType;
}

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

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

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

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

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

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 #

Создайте SavedBankCardModuleInputData:

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

Запустите процесс и получите токен в 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));

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

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

Попробуйте команду pod update YooKassaPayments
В некоторых сложных случаях рекомендуем сбросить кэш cocoapods.

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

При сборке получили ошибку 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 #

В 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 файл для получения дополнительной информации.

yookassa_payments_flutter 2.0.1
yookassa_payments_flutter: ^2.0.1 copied to clipboard

Metadata

YooKassa Payments SDK for Flutter #

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

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

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

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

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

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

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

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

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

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

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

TokenizationModuleInputData #

SavedBankCardModuleInputData #

TokenizationSettings #

TestModeSettings #

Amount #

Currency #

CustomizationSettings #

SavePaymentMethod #

Логирование #

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

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

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

FAQ #

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

Лицензия #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

License

Dependencies

More

yookassa_payments_flutter 2.0.1 yookassa_payments_flutter: ^2.0.1 copied to clipboard

Metadata

YooKassa Payments SDK for Flutter #

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

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

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

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

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

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

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

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

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

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

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

TokenizationModuleInputData #

SavedBankCardModuleInputData #

TokenizationSettings #

TestModeSettings #

Amount #

Currency #

CustomizationSettings #

SavePaymentMethod #

Логирование #

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

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

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

FAQ #

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

Лицензия #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

License

Dependencies

More

yookassa_payments_flutter 2.0.1
yookassa_payments_flutter: ^2.0.1 copied to clipboard