Интеграция 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 раза выше конверсию и значительно лучший пользовательский опыт.

Типовые ошибки и их решения

Что входит в работу

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

Сроки

Базовая интеграция занимает 2–3 дня. Если требуется кастомный UI или дополнительные методы — до 5 дней. Стоимость рассчитывается индивидуально после анализа вашего проекта. Свяжитесь с нами — мы бесплатно оценим объём работ и предложим оптимальное решение. Гарантируем, что платёжный экран будет работать стабильно даже под высокой нагрузкой.

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