Интеграция 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-Кассу без ошибок.