tinkoff_sdk

Description:

tinkoff sdk

Tinkoff SDK для Flutter #
SDK позволяет интегрировать Интернет-Эквайринг от Тинькофф в мобильные приложения на Flutter.
Возможности SDK #

✅ Прием платежей (в том числе рекуррентных)
✅ Завершение оплаты в приложении
✅ Оплата с помощью:

✅ СБП (Системы быстрых платежей)

✅ TinkoffPay
✅ QR-кода (статический и динамический)




✅ Получение информации о картах клиента

✅ Добавление новой банковской карты

✅ Управление сохраненными картами





Содержание #

Tinkoff SDK для Flutter

Возможности SDK

Содержание
Требования

Android
iOS


Использование

Подготовка к работе
Проведение оплаты
СБП

iOS
Android


Оплата с помощью QR-кода

Статический QR-код
Динамический QR-код


T-Pay

iOS
Android


Список привязанных карт
Добавление новой банковской карты
Решение возможных проблем

Ошибка 309. Неверные параметры









Требования #
Для работы Tinkoff SDK необходимо:
Android #

Поддержка Android 7.0 и выше (API level 24)
Использование FragmentActivity вместо Activity

MainActivity.kt
import androidx.annotation.NonNull;
import io.flutter.embedding.android.FlutterFragmentActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugins.GeneratedPluginRegistrant

class MainActivity: FlutterFragmentActivity() {
override fun configureFlutterEngine(@NonNull flutterEngine: FlutterEngine) {
GeneratedPluginRegistrant.registerWith(flutterEngine);
}
}
copied to clipboard
или MainActivity.java
import androidx.annotation.NonNull;
import io.flutter.embedding.android.FlutterFragmentActivity;
import io.flutter.embedding.engine.FlutterEngine;
import io.flutter.plugins.GeneratedPluginRegistrant;

public class MainActivity extends FlutterFragmentActivity {
@Override
public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
GeneratedPluginRegistrant.registerWith(flutterEngine);
}
}
copied to clipboard
iOS #

Поддержка iOS 13.0 и выше

Использование #
Подготовка к работе #
Для начала работы с SDK вам понадобятся:

Terminal Key
PublicKey
Эти данные вы получите после подключения к Интернет-Эквайрингу.


import 'package:tinkoff_sdk/tinkoff_sdk.dart';

static const _TERMINAL_KEY = 'TERMINAL_KEY';
static const _PUBLIC_KEY = 'PUBLIC_KEY';

final TinkoffSdk acquiring = TinkoffSdk();

Future<void> activate() async {
await acquiring.activate(
terminalKey: _TERMINAL_KEY,
publicKey: _PUBLIC_KEY,
// SDK позволяет настроить режим работы (debug/prod). По умолчанию - режим prod.
// Чтобы настроить debug режим, установите параметры:
isDeveloperMode: true,
logging: true,
);
}
copied to clipboard
❗ Обратите особое внимание на параметр isDeveloperMode.
Используйте isDeveloperMode: true только с данными тестового терминала (terminal key и public key), а isDeveloperMode: false только с данными боевого терминала.
При попытке использовать isDeveloperMode: true с данными боевого терминала (и наоборот) возникнет ошибка на этапе инициализации TinkoffSdk в приложении.
Проведение оплаты #
Для проведения оплаты нужно вызвать метод openPaymentScreen.

import 'package:tinkoff_sdk/tinkoff_sdk.dart';

final tinkoffSdk = TinkoffSdk();

Future<TinkoffResult> openPaymentScreen({
required String terminalKey,
required String publicKey,
required OrderOptions orderOptions,
required CustomerOptions customerOptions,
FeaturesOptions featuresOptions = const FeaturesOptions(),
}) async {
await tinkoffSdk.openPaymentScreen(
terminalKey: terminalKey,
publicKey: publicKey,
orderOptions: orderOptions,
customerOptions: customerOptions,
featuresOptions: featuresOptions,
);
}

copied to clipboard
Метод вернет результат типа TinkoffResult.

Для проведения рекуррентного платежа добавьте в OrderOptions поле recurrentPayment: true.
final orderOptions = OrderOptions(
recurrentPayment: true,
);
copied to clipboard
TASDK предоставляет возможность инициализировать платеж вне приложения (например, на сервере) и завершить его в приложении, используя SDK.
Для проведения такого сценария необходимо:

Инициализировать платеж вне приложения используя метод /v2/Init (подробнее здесь)
После успешной инициализации платежа получить в ответе поле paymentId
Взять значение paymentId и провести завершение оплаты из приложения с помощью метода .finishPayment()

import 'package:tinkoff_sdk/tinkoff_sdk.dart';

final tinkoffSdk = TinkoffSdk();

Future<TinkoffResult> finishPayment({
required String terminalKey,
required String publicKey,
required String paymentId,
required OrderOptions orderOptions,
CustomerOptions? customerOptions,
FeaturesOptions featuresOptions = const FeaturesOptions(),
}) async {
final result = await tinkoffSdk.finishPayment(
terminalKey: terminalKey,
publicKey: publicKey,
paymentId: paymentId,
orderOptions: orderOptions,
customerOptions: customerOptions,
featuresOptions: featuresOptions,
);

return result;
}
copied to clipboard
СБП #
❗ Перед началом работы с СБП (Системой быстрых платежей) включите "Оплату через Систему быстрых платежей" в Личном кабинете Интернет-Эквайринга.
Информация взята из документации TASDK iOS
iOS
Перед началом работы добавьте в Info.plist список банков, поддерживающих СБП.
<key>LSApplicationQueriesSchemes</key>
<array>
<string>bank100000000111</string>
<string>bank100000000004</string>
<string>bank110000000005</string>
<string>bank100000000008</string>
</array>
copied to clipboard
❗ В список можно внести не более 50-ти схем

Android
Дополнительных шагов не требуется

После выполнения всех необходимых требований, возможность оплаты через СБП появится в общей форме оплаты.

При выборе конкретного банка из списка произойдет переход в соответствующее банковское приложение.
Оплата с помощью QR-кода #
Оплата с помощью QR-кода может быть проведена двумя способами: через статический или динамический QR-код.
❗ Для работы оплаты по QR-коду включите "Оплату через Систему быстрых платежей" в Личном кабинете Интернет-Эквайринга.
Статический QR-код
Отображает экран с многразовым QR-кодом, отсканировав который пользователь сможет провести оплату по СБП (Системе быстрых платежей).
❗ При данном способе оплаты SDK никак не отслеживает статус платежа
Для отображения статического QR-кода вызовите метод showStaticQRCode.

import 'package:tinkoff_sdk/tinkoff_sdk.dart';

final tinkoffSdk = TinkoffSdk();

Future<void> showStaticQrCode() async {
await tinkoffSdk.showStaticQRCode();
}
copied to clipboard
Динамический QR-код
Отображает экран с одноразовым QR-кодом, отсканировав который пользователь сможет провести оплату по СБП (Системе быстрых платежей).
Для отображения динамического QR-кода вызовите метод showDynamicQRCode.

import 'package:tinkoff_sdk/tinkoff_sdk.dart';

final tinkoffSdk = TinkoffSdk();

Future<TinkoffResult> showDynamicQRCode({
required AndroidDynamicQrCode androidDynamicQrCode,
required IosDynamicQrCode iOSDynamicQrCode,
}) async {
await tinkoffSdk.showDynamicQRCode(
androidDynamicQrCode: androidDynamicQrCode,
iOSDynamicQrCode: iOSDynamicQrCode,
);
}
copied to clipboard
Метод вернет результат типа TinkoffResult.
T-Pay #
❗ Перед началом работы подключите "Оплату через T-Pay" в Личном кабинете Интернет-Эквайринга
Информация взята из документации Tinkoff ASDK iOS
iOS
Прежде всего для корректной работы T-Pay в вашем приложении необходимо добавить в Info.plist в массив по ключу LSApplicationQueriesSchemes значение bank100000000004:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>bank100000000004</string>
</array>
copied to clipboard
Так приложение сможет определить наличие приложения Т-Банк на устройстве пользователя.
Android
Дополнительных шагов не требуется
Список привязанных карт #
Вы можете отобразить список привязанных карт пользователя. Для этого вызовите метод getCardList:
import 'package:tinkoff_sdk/tinkoff_sdk.dart';

final tinkoffSdk = TinkoffSdk();

Future<void> getCardsList({
required String terminalKey,
required String publicKey,
required CustomerOptions customerOptions,
}) async {
await tinkoffSdk.getCardList(
terminalKey: terminalKey,
publicKey: publicKey,
customerOptions: _customerOptions,
);
}
copied to clipboard
Добавление новой банковской карты #
Вы можете отобразить на новом экране форму добавления новой банковской карты. Для этого вызовите метод openAttachCardScreen:
import 'package:tinkoff_sdk/tinkoff_sdk.dart';

final tinkoffSdk = TinkoffSdk();

Future<void> openAttachCardScreen({
required String terminalKey,
required String publicKey,
required CustomerOptions customerOptions,
FeaturesOptions featuresOptions = const FeaturesOptions(),
}) async {
await tinkoffSdk.openAttachCardScreen(
terminalKey: terminalKey,
publicKey: publicKey,
customerOptions: customerOptions,
featuresOptions: featuresOptions,
);
}
copied to clipboard
Решение возможных проблем #
Ошибка 309. Неверные параметры
"Details":"{request.validate.expected.receipt}"
Ошибка появляется в случае, если в вашем магазине подключена Онлайн-Касса, которой необходимо к каждому платежу прикреплять чек.
Решение
В методе openPaymentScreen в OrderOptions необходимо добавить следующее:

Поле чека (receipt) с непустым списком позиций чека (items)
Для каждой позиции в чеке (Item105) добавьте поле quantity (количество/вес товара)
В поле receipt в Receipt105/Receipt12 добавьте поля taxation (cистема налогообложения) и email/phone (e-mail или номер телефона).

Пример:
import 'package:tinkoff_sdk/tinkoff_sdk.dart';

final tinkoffSdk = TinkoffSdk();

final orderOptions = OrderOptions(
orderId: '111111',
amount: 1000,
receipt: Receipt105(
taxation: Taxation.osn, // добавить это
email: '[email protected]', // это (почту или телефон)
items: [
Item105(
name: 'Успокоительное',
amount: 1000,
tax: Tax.vat0,
paymentMethod: PaymentMethod.fullPrepayment,
price: 1000,
quantity: 1, // и это
),
],
)
);

Future<TinkoffResult> openPaymentScreen({
required String terminalKey,
required String publicKey,
required CustomerOptions customerOptions,
FeaturesOptions featuresOptions = const FeaturesOptions(),
}) async {
await tinkoffSdk.openPaymentScreen(
terminalKey: terminalKey,
publicKey: publicKey,
orderOptions: orderOptions,
customerOptions: customerOptions,
featuresOptions: featuresOptions,
);
}
copied to clipboard