Інтеграція T-Каси (Тінькофф) у мобільний додаток: iOS та Android

Інтеграція платіжного шлюзу T-Каси (Тінькофф) у мобільний додаток

Зауважимо: коли клієнт натискає «Оплатити», а додаток зависає з порожнім екраном — це катастрофа. Ми таке бачили не раз: SDK підключено, але платіжний екран не відкривається, або платіж падає з помилкою 0 (Invalid Token). Найчастіше проблема в підписі запиту або неправильній конфігурації терміналу. Наша команда за останні роки інтегрувала T-Касу (раніше Тінькофф Каса) у десятки проектів з аудиторією від 1 000 до 100 000 користувачів. Нижче — перевірена схема, яка працює з першого разу.

Чому варто обрати нативну інтеграцію T-Каси?

T-Каса надає готові нативні SDK для iOS та Android. На відміну від WebView-обгорток, нативний платіжний екран завантажується миттєво, підтримує Face ID/Touch ID для авторизації та коректно обробляє повернення після оплати. SDK також включає захист від фроду та автоматично підставляє збережені картки. Це дає конверсію в оплату на 15–20% вище, ніж через браузерний варіант. Згідно з офіційною документацією Tinkoff Acquiring SDK, нативний підхід мінімізує кількість кроків користувача.

Як виглядає основний flow?

T-Каса працює за двоетапною схемою: спочатку сервер ініціалізує платіж та отримує paymentId, потім SDK на клієнті проводить його. Це стандартна для платіжних шлюзів схема, але саме тут найчастіше помиляються.

Серверна ініціалізація:

POST https://securepay.tinkoff.ru/v2/Init { "TerminalKey": "your_terminal_key", "Amount": 150000, "OrderId": "ORDER-1234", "Description": "Оплата замовлення", "Token": "sha256_signature" } 

Відповідь містить PaymentId та PaymentURL. PaymentId передається в SDK для проведення платежу в нативному UI.

Як підключити T-Касу: покрокова інструкція

Крок 1: Серверна ініціалізація

Переконайтеся, що сервер формує коректний Token — SHA-256 хеш від конкатенації параметрів (в алфавітному порядку ключів) із додаванням Password в кінці. Використовуйте офіційні бібліотеки для генерації.

Крок 2: Запуск платіжного екрану на клієнті

Після отримання PaymentId передайте його в SDK. Приклад для Android:

val tinkoffAcquiring = TinkoffAcquiring( context, terminalKey = "your_terminal_key", publicKey = "your_public_key" ) val paymentOptions = PaymentOptions().setOptions { setTerminalParams( terminalKey = "your_terminal_key", publicKey = "your_public_key" ) orderOptions { orderId = "ORDER-1234" amount = Money.ofRubles(1500) title = "Замовлення №1234" description = "Оплата замовлення" savingAsParentPayment = false } featuresOptions { useSecureKeyboard = true cameraCardScanner = CameraCardIOScanner() fpsEnabled = true tinkoffPayEnabled = true } } val launcher = registerForActivityResult(TinkoffAcquiring.createPaymentContract(context)) { result -> when (result.status) { AsdkState.Success -> handleSuccess(result.paymentId) AsdkState.Cancelled -> {} AsdkState.Error -> handleError(result.error) else -> {} } } tinkoffAcquiring.openPaymentScreen( activity = this, paymentOptions = paymentOptions, launcher = launcher ) 

Для iOS (AcquiringUISDK):

import TinkoffASDKUI let credential = AcquiringSdkCredential( terminalKey: "your_terminal_key", publicKey: "your_public_key" ) let acquiringSDK = try AcquiringUISDK(credential: credential) let paymentData = PaymentInitData( amount: 150000, orderId: "ORDER-1234", customerKey: "user_123" ) acquiringSDK.presentPaymentView( on: self, paymentData: paymentData, configuration: AcquiringViewConfiguration() ) { result in switch result { case .success(let paymentInfo): print("Payment ID: \(paymentInfo.paymentId)") case .failure(let error): print("Error: \(error)") case .cancelled: break } } 

Як ми підключали T-Касу в проекті з 100 000 користувачів

Розповім на конкретному кейсі. Наш клієнт — маркетплейс із нативним Android-додатком. До нас оплата йшла через WebView і втрачала 30% замовлень на етапі підтвердження. Ми перевели все на SDK T-Каси, налаштували СБП і Tinkoff Pay, додали кастомний екран вибору методу оплати. Результат: конверсія зросла з 12% до 28%, підтримка перестала отримувати скарги на «завислу оплату». Ключові моменти інтеграції:

• Серверна ініціалізація платежу з коректним Token (SHA-256).
• Використання CameraCardIOScanner на iOS та ML Kit на Android для введення картки.
• Налаштування колбеків через webhook: ми отримуємо статус платежу в реальному часі та оновлюємо замовлення без участі користувача.

Додаткові налаштування

Tinkoff Pay

Tinkoff Pay відкриває додаток Т-Банку для підтвердження платежу. Для роботи потрібно, щоб Т-Банк був встановлений на пристрої. SDK перевіряє це автоматично через UIApplication.canOpenURL (iOS) або PackageManager.getLaunchIntentForPackage (Android) і ховає кнопку, якщо додаток не знайдено.

Підпис запитів (Token)

Усі серверні запити до API T-Каси підписуються через SHA-256: конкатенація значень параметрів + Password в алфавітному порядку ключів. Неправильний token — часта причина помилки 0 (Invalid Token) при ініціалізації платежу. Ми настійно рекомендуємо перевіряти генерацію tokens на стороні сервера, використовуючи офіційні бібліотеки.

Порівняння нативної інтеграції та WebView

З таблиці видно, що нативний SDK дає в 2–3 рази вищу конверсію та значно кращий користувацький досвід.

Типові помилки та їх вирішення

Що входить у роботу

• Підключення SDK iOS / Android
• Серверна ініціалізація платежу з коректним підписом
• Налаштування опцій: СБП, Tinkoff Pay, збереження картки
• Обробка статусів та Webhook підтвердження
• Тестування через тестовий термінал
• Верифікація платежів через колбеки

Терміни

Базова інтеграція займає 2–3 дні. Якщо потрібен кастомний UI або додаткові методи — до 5 днів. Вартість розраховується індивідуально після аналізу вашого проекту. Зв'яжіться з нами — ми безкоштовно оцінимо обсяг робіт і запропонуємо оптимальне рішення. Гарантуємо, що платіжний екран працюватиме стабільно навіть під високим навантаженням.

За даними Tinkoff ( Tinkoff Developer Portal ), нативний SDK підвищує конверсію в оплату на 20–30%. Отримайте консультацію інженера — ми допоможемо підключити T-Касу без помилок.