Flutter YooKassa Payments SDK #

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

В SDK входят готовые платежные интерфейсы (форма оплаты и всё, что с ней связано).

С помощью SDK можно получать токены для проведения оплаты с банковской карты, Google Pay, Сбербанка или из кошелька в ЮMoney.

Минимально поддерживаемая версия ios sdk: 10.0. Минимально поддерживаемая версия android sdk: 21(Android 5).

YooKassa Payments SDK

Changelog #

Ссылка на Changelog

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

Добавьте зависимость в ваш pubspec.yaml

dependencies:
  flutter_yookassa_sdk: ^0.1.0

iOS #

Добавьте следующие строки в ваш Podfile.

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/yoomoney-tech/cocoa-pod-specs.git'

...
target 'Runner' do
  ...

  pod 'YooKassaPayments',
        :git => 'https://github.com/yoomoney/yookassa-payments-swift.git',
        :tag => '6.2.0'

  ...
end
...

Подключение TMXProfiling и TMXProfilingConnections #

Чтобы получить файл .xcframework, зарегистрируйтесь в ЮKassa и сообщите вашему менеджеру, что хотите подключить мобильный SDK.

Используя Finder или другой файловый менеджер добавьте библиотеки TMXProfiling.xcframework и TMXProfilingConnections.xcframework в папку c вашим проектом.
В разделе General у основного таргета проекта добавьте TMXProfiling.xcframework и TMXProfilingConnections.xcframework в Frameworks, Libraries, and Embedded Content.
TMXProfiling.xcframework и TMXProfilingConnections.xcframework должны быть добавлены как Embed & Sign

Android #

Конфигурация #

Для подключения библиотеки пропишите в build.gradle:

...
ext.kotlin_version = '1.4.32'
...

Попросите у менеджера по подключению библиотеку ThreatMetrix Android SDK 6.2-97.aar. Создайте папку libs (android/app/libs) в модуле где подключаете sdk и добавьте туда файл ThreatMetrix Android SDK 5.4-73.aar. В android/app/build.gradle того же модуля в dependencies добавьте:

dependencies {
    implementation fileTree(dir: "libs", include: ["*.aar"])
}

Настройка приложения при продаже цифровых товаров #

Если в вашем приложении продаются цифровые товары, нужно отключить Google Pay из списка платежных опций. Для этого добавьте в AndroidManifest следующий код:

<manifest ... xmlns:tools="http://schemas.android.com/tools">
...
<meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    tools:node="remove" />
...
</manifest>

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

Создайте TokenizationModuleInputData (понадобится ключ для клиентских приложений из личного кабинета ЮKassa). В этой модели передаются параметры платежа (валюта и сумма) и параметры платежной формы, которые увидит пользователь при оплате (способы оплаты, название магазина и описание заказа).

Для работы с сущностями FlutterYookassaSdk импортируйте зависимости в исходный файл

import 'package:flutter_yookassa_sdk/flutter_yookassa_sdk.dart';

Пример создания TokenizationModuleInputData:

final inputData = TokenizationModuleInputData(
  clientApplicationKey: "live_AAAAAAAAAAAAAAAAAAAA",
  shopName: "Космические объекты",
  purchaseDescription: "Комета повышенной яркости, период обращения — 112 лет",
  amount: const Amount(value: 999, currency: Currency.rub()),
  savePaymentMethod: SavePaymentMethod.userSelects,
  shopId: '12345',
  tokenizationSettings: TokenizationSettings(
    paymentMethodTypes: PaymentMethodTypes.all(),
    showYooKassaLogo: false,
  ),
  moneyAuthClientId: 'client_id',
  googlePayParameters: GooglePayParameters(),
);

Запустите процесс токенизации

try {
  final paymentData =
    await FlutterYookassaSdk.instance.tokenization(inputData);
} on YooKassaException catch (err) {
  /// Обработка ошибки
}

При успешной токенизации. Он возвращает PaymentData, который состоит из:

token (String) - платежный токен, см. Использование платежного токена;
paymentMethod (String) - тип платежного средства.

ЮMoney #

Если среди платёжных методов есть кошелёк ЮMoney, необходимо зарегистрировать приложение и получить authCenterClientId. В остальных случаях этот шаг можно пропустить.

Для подключения способа оплаты ЮMoney необходимо:

Получить client id центра авторизации системы ЮMoney.
При создании TokenizationModuleInputData передать client id в параметре moneyAuthClientId

Как получить `client id` центра авторизации системы `ЮMoney`

Авторизуйтесь на yookassa.ru
Перейти на страницу регистрации клиентов СЦА - yookassa.ru/oauth/v2/client
Нажать Зарегистрировать
Заполнить поля:
4.1. "Название" - required поле, отображается при выдаче прав и в списке приложений.
4.2. "Описание" - optional поле, отображается у пользователя в списке приложений.
4.3. "Ссылка на сайт приложения" - optional поле, отображается у пользователя в списке приложений.
4.4. "Код подтверждения" - выбрать Передавать в Callback URL, можно указывать любое значение, например ссылку на сайт.
Выбрать доступы:
5.1. Кошелёк ЮMoney -> Просмотр
5.2. Профиль ЮMoney -> Просмотр
5.3. Доступы. Тут есть три раздела API ЮKassa, Кошелёк ЮMoney, Профиль ЮMoney.
- В разделе Кошелёк ЮMoney выдайте разрешение на чтение баланса кошелька пользователя. Для этого в разделе БАЛАНС КОШЕЛЬКА поставьте галку на против поля Просмотр;
- Откройте раздел Профиль ЮMoney и выдайте разрешение на чтение телефона, почты, имени и аватара пользователя. Для этого в разделе ТЕЛЕФОН, ПОЧТА, ИМЯ И АВАТАР ПОЛЬЗОВАТЕЛЯ поставьте галку на против поля Просмотр;
Нажать Зарегистрировать

Передать `client id` в параметре `moneyAuthClientId`

При создании TokenizationModuleInputData передать client id в параметре moneyAuthClientId

final inputData = TokenizationModuleInputData(
    ...
    moneyAuthClientId: "client_id")

Чтобы провести платеж:

При создании TokenizationModuleInputData передайте значение .yooMoney в paymentMethodTypes.

final inputData = TokenizationModuleInputData(
    ...
    tokenizationSettings: const TokenizationSettings(
      paymentMethodTypes: PaymentMethodTypes.yooMoney(),
    ),
    moneyAuthClientId: 'your_client_id',
);

Получите токен.
Создайте платеж с токеном по API ЮKassa.

Поддержка авторизации через мобильное приложение

В TokenizationModuleInputData необходимо передавать applicationScheme – схема для возврата в приложение после успешной авторизации в ЮMoney через мобильное приложение.

Пример applicationScheme:

final inputData = TokenizationModuleInputData(
    ...
    applicationScheme: 'examplescheme://'

В AppDelegate импортировать зависимость YooKassaPayments:
```
import YooKassaPayments
```
Добавить обработку ссылок через YKSdk в AppDelegate:

func application(
    _ application: UIApplication,
    open url: URL,
    sourceApplication: String?, 
    annotation: Any
) -> Bool {
    return YKSdk.shared.handleOpen(
        url: url,
        sourceApplication: sourceApplication
    )
}

@available(iOS 9.0, *)
func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    return YKSdk.shared.handleOpen(
        url: url,
        sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String
    )
}

В Info.plist добавьте следующие строки:

<key>LSApplicationQueriesSchemes</key>
<array>
	<string>yoomoneyauth</string>
</array>
<key>CFBundleURLTypes</key>
<array>
	<dict>
		<key>CFBundleTypeRole</key>
		<string>Editor</string>
		<key>CFBundleURLName</key>
		<string>${BUNDLE_ID}</string>
		<key>CFBundleURLSchemes</key>
		<array>
			<string>examplescheme</string>
		</array>
	</dict>
</array>

где examplescheme - схема для открытия вашего приложения, которую вы указали в applicationScheme при создании TokenizationModuleInputData. Через эту схему будет открываться ваше приложение после успешной авторизации в ЮMoney через мобильное приложение.

Банковская карта #

При создании TokenizationModuleInputData передайте значение .bankcard в paymentMethodTypes.

final inputData = TokenizationModuleInputData(
    ...
    tokenizationSettings: const TokenizationSettings(
      paymentMethodTypes: PaymentMethodTypes.bankCard(),
    ),
);

Получите токен.
Создайте платеж с токеном по API ЮKassa.

SberPay #

iOS SberPay #

С помощью SDK можно провести платеж через «Мобильный банк» Сбербанка — с подтверждением оплаты через приложение Сбербанк Онлайн, если оно установленно, иначе с подтверждением по смс.

В TokenizationModuleInputData необходимо передавать applicationScheme – схема для возврата в приложение после успешной оплаты с помощью SberPay в приложении СберБанк Онлайн.

Пример applicationScheme:

final inputData = TokenizationModuleInputData(
      ...
      applicationScheme: 'examplescheme://'

Чтобы провести платёж:

При создании TokenizationModuleInputData передайте значение .sberbank в paymentMethodTypes.
Получите токен.
Создайте платеж с токеном по API ЮKassa.

Для подтверждения платежа через приложение СберБанк Онлайн:

В AppDelegate импортируйте зависимость YooKassaPayments:
```
import YooKassaPayments
```
Добавьте обработку ссылок через YKSdk в AppDelegate:

func application(
    _ application: UIApplication,
    open url: URL,
    sourceApplication: String?, 
    annotation: Any
) -> Bool {
    return YKSdk.shared.handleOpen(
        url: url,
        sourceApplication: sourceApplication
    )
}

@available(iOS 9.0, *)
func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    return YKSdk.shared.handleOpen(
        url: url,
        sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String
    )
}

В Info.plist добавьте следующие строки:

<key>LSApplicationQueriesSchemes</key>
<array>
	<string>sberpay</string>
</array>
<key>CFBundleURLTypes</key>
<array>
	<dict>
		<key>CFBundleTypeRole</key>
		<string>Editor</string>
		<key>CFBundleURLName</key>
		<string>${BUNDLE_ID}</string>
		<key>CFBundleURLSchemes</key>
		<array>
			<string>examplescheme</string>
		</array>
	</dict>
</array>

Android SberPay #

Для работы sdk нужно настроить схему вашего приложения для обработки deeplink. Это необходимо сделать для оплаты через sberpay. Нужно добавить в ваш файл build.gradle в блок android.defaultConfig строку resValue "string", "ym_app_scheme", "your_unique_app_shceme"

android {
    defaultConfig {
        resValue "string", "ym_app_scheme", "your_unique_app_shceme"
    }
}

Или добавить в ваш strings.xml строку вида:

<resources>
    <string name="ym_app_scheme" translatable="false">your_unique_app_shceme</string>
</resources>

Где your_unique_app_shceme - это уникальное название вашего приложения, если вы уже обрабатывете deeplink в своём приложении, то можно использовать готовую схему вашего приложения. Если ранее в проекте вы не обрабатывали deeplink, можно придумать уникальную схему для вашего приложения, состоящую из латинских букв.

Apple Pay #

Чтобы подключить Apple Pay, нужно передать в ЮKassa сертификат, с помощью которого Apple будет шифровать данные банковских карт.

Для этого:

Напишите менеджеру и попросите создать для вас запрос на сертификат (.csr).
Создайте сертификат в панели разработчика Apple (используйте .csr).
Скачайте получившийся сертификат и пришлите менеджеру.

Подробная инструкция (см. раздел 2 «Обмен сертификатами с Apple»)

Включите Apple Pay в Xcode.

Чтобы провести платеж:

При инициализации объекта TokenizationModuleInputData необходимо передать apple pay identifier в параметр applePayMerchantIdentifier.

final inputData = TokenizationModuleInputData(
    ...
    applePayMerchantIdentifier: "com.example.identifier"

Получите токен.
Создайте платеж с токеном по API ЮKassa.

Использование платежного токена #

Необходимо получить у менеджера ЮKassa разрешение на проведение платежей с использованием токена. Токен одноразовый, срок действия — 1 час. Если не создать платеж в течение часа, токен нужно будет запрашивать заново.

В платежном токене содержатся данные о сценарии подтверждения платежа. После получения платежного токена Вы можете создать платеж, в параметре payment_token передайте платежный токен. Если платеж проводится с аутентификацией по 3-D Secure, используйте confirmation_url, который придет в объекте Платежа. Используйте confirmation_url для запуска 3-D Secure, см. 3DSecure.

Так же, Вы можете получить информацию о платеже

3DSecure #

Вызовите 3DSecure

await FlutterYookassaSdk.instance.confirm3dsCheckout(
      confirmationUrl: confirmationUrl,
      paymentMethodType: paymentMethod,
);

После успешного 3DSecure не гарантируется что успешно, рекомендуется запросить статус платежа
Завершите процесс покупки ЮКассу

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

У вас есть возможность включить логирование всех сетевых запросов.
Для этого необходимо при создании TokenizationModuleInputData передать isLoggingEnabled: true

final inputData = TokenizationModuleInputData(
    ...
    isLoggingEnabled: true)

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

У вас есть возможность запустить мобильный SDK в тестовом режиме.
Тестовый режим не выполняет никаких сетевых запросов и имитирует ответ от сервера.

Если вы хотите запустить SDK в тестовом режиме, необходимо:

Сконфигурировать объект с типом TestModeSettings.

final testModeSettings = TestModeSettings(
  paymentAuthorizationPassed: true,
  cardsCount: 5,
  charge: Amount(value: 50, currency: Currency.rub()),
  enablePaymentError: false,
);

Передать его в TokenizationModuleInputData в параметре testModeSettings:

final inputData = TokenizationModuleInputData(
    ...
    testModeSettings: testModeSettings)

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

По умолчанию используется цвет blueRibbon. Цвет основных элементов, кнопки, переключатели, поля ввода.

Сконфигурировать объект CustomizationSettings и передать его в параметр customizationSettings объекта TokenizationModuleInputData.

final inputData = TokenizationModuleInputData(
    ...
    customizationSettings: CustomizationSettings(mainScheme: Colors.blue ),
);

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

      final paymentData = await FlutterYookassaSdk.instance.bankCardRepeat(
        BankCardRepeatModuleInputData(
          clientApplicationKey: clientApplicationKey,
          shopName: shopName,
          purchaseDescription: purchaseDescription,
          shopId: 'mock_id',
          paymentMethodId: 'method_id',
          amount: Amount(value: value, currency: currency),
          savePaymentMethod: savePaymentMethod,
        ),
      );

flutter_yookassa_sdk 0.1.2
flutter_yookassa_sdk: ^0.1.2 copied to clipboard

Metadata

Flutter YooKassa Payments SDK #

Changelog #

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

iOS #

Подключение TMXProfiling и TMXProfilingConnections #

Android #

Конфигурация #

Настройка приложения при продаже цифровых товаров #

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

ЮMoney #

Как получить `client id` центра авторизации системы `ЮMoney`

Передать `client id` в параметре `moneyAuthClientId`

Поддержка авторизации через мобильное приложение

Банковская карта #

SberPay #

iOS SberPay #

Android SberPay #

Apple Pay #

Использование платежного токена #

3DSecure #

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

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

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

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

← Metadata

Publisher

Metadata

Documentation

License

Dependencies

More

flutter_yookassa_sdk 0.1.2 flutter_yookassa_sdk: ^0.1.2 copied to clipboard

Metadata

Flutter YooKassa Payments SDK #

Changelog #

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

iOS #

Подключение TMXProfiling и TMXProfilingConnections #

Android #

Конфигурация #

Настройка приложения при продаже цифровых товаров #

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

ЮMoney #

Как получить client id центра авторизации системы ЮMoney

Передать client id в параметре moneyAuthClientId

Поддержка авторизации через мобильное приложение

Банковская карта #

SberPay #

iOS SberPay #

Android SberPay #

Apple Pay #

Использование платежного токена #

3DSecure #

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

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

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

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

← Metadata

Publisher

Metadata

Documentation

License

Dependencies

More

flutter_yookassa_sdk 0.1.2
flutter_yookassa_sdk: ^0.1.2 copied to clipboard

Как получить `client id` центра авторизации системы `ЮMoney`

Передать `client id` в параметре `moneyAuthClientId`