TACAP API — QR-платежи Т-Банка

by Т-Банк

Интегрируйте POS- или кассовое ПО с протоколом Т-Банка для создания динамического QR-кода, запроса статуса, отмены и возврата QR-операций.

💳 Финансы

Что делает API

TACAP описывает протокол обмена между банковским ПО и ПО вендоров для торговых QR-операций. В нем есть отдельные семейства методов для динамического и кассового QR, JSON/XML, прямого сценария и интеграции агрегатора. Для JSON динамического QR типичный цикл включает генерацию платежного QR, опрос QUERY, а при необходимости CANCEL или REFUND. Каждый запрос/ответ подписывается; интеграция использует данные терминала и ключ подписи из подготовки оборудования. Точный URL и набор полей зависят от выбранного семейства протокола.

Когда использовать

  • Кассовое приложение формирует динамический QR-код для конкретной покупки и отображает его покупателю.
  • После выдачи кода POS периодически запрашивает QUERY, чтобы показать итог оплаты; кассир инициирует CANCEL при отмене, когда сценарий и статус операции это допускают.

Подключение и ограничения

Авторизация
Обычный JSON-протокол динамического QR подписывает каждое сообщение по алгоритму HMAC_SHA256 с ключом signKey, загруженным в ходе первичной настройки через TMS; перед подписью учитываются перечисленные документацией поля и их порядок. Для TACAP требуются сертификаты Минцифры. В варианте для агрегаторов есть отдельный endpoint, сведения об agentId и собственные поля; не смешивайте ключи и host между вариантами.
Что учесть
Это не универсальный REST API с Bearer-токеном: запросы используют JSON/XML-конверт протокола и криптографическую подпись. Для стандартного JSON динамического QR документация указывает https://qrpay.tinkoff.ru/qrpay/external/api/v1/operations/QUERY; для XML endpoint общий /send; агрегаторные методы используют другой host и URL. Порядковый номер outTransactionNo на POS должен быть уникальным и увеличиваться для каждого запроса. Перед подписанием totalAmount нормализуется до двух знаков после запятой. Публичные страницы для разных подтипов показывают различные адреса серверов; тестовый endpoint нужно сверять для выбранной интеграции.

Пример использования

Подготовьте доступ по инструкции выше и замените параметры своими. Пример не выполняется на этой странице.

# Только чтение статуса ранее созданной операции; замените значения параметрами POS.
curl --silent --show-error --fail-with-body --request POST \
  --url "https://qrpay.tinkoff.ru/qrpay/external/api/v1/operations/QUERY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "currency": "${TACAP_CURRENCY:?Укажите валюту исходного платежа}",
  "mchId": "${TACAP_MCH_ID:?Укажите MID}",
  "outTransactionNo": ${TACAP_OUT_TRANSACTION_NO:?Укажите порядковый номер запроса POS},
  "oriTransactionNo": ${TACAP_ORI_TRANSACTION_NO:?Укажите outTradeNo исходного QRPAY},
  "signType": "HMAC_SHA256",
  "signature": "${TACAP_SIGNATURE:?Рассчитайте подпись запроса}",
  "terId": "${TACAP_TER_ID:?Укажите TID терминала}",
  "timeStart": "${TACAP_TIME_START:?Укажите время в формате yyyy-MM-ddTHH:mm:ss}",
  "totalAmount": "${TACAP_TOTAL_AMOUNT:?Укажите исходную сумму как number(9,2)}",
  "tradeType": "pay.paxpay.native",
  "version": "V1.0"
}
JSON
Результат
QUERY проверяет статус ранее созданной операции. В описании этого метода опубликован успешный код ответа, но схема тела ответа отдельно не раскрыта. Общая документация TACAP подтверждает подпись ответных JSON-сообщений и перечисляет code и msg среди атрибутов подписи. Для QUERY код SUCCESS означает одобрение, USINGPAY — обработку, UNKNOWN — неизвестный статус; для двух последних документация предписывает повторить запрос статуса. Перед проверкой подписи учтите порядок полей и нормализацию totalAmount до двух десятичных знаков.
Ошибки
Для QUERY код SUCCESS означает одобрение операции, USINGPAY — обработку, UNKNOWN — неизвестный статус; при двух последних кодах документация предписывает повторять запрос статуса. SIGNERROR указывает на проблему подписи, PARAMETERERROR — на неверный или отсутствующий параметр. Значение кодов CANCEL и REFUND сверяйте отдельно: промежуточный ответ не является основанием создать новый платёж.

Сверено с документацией: .

Порядок интеграции

  1. Уточнить тип подключения (кассовый или динамический QR; JSON/XML; агрегатор или устройство) и получить соответствующую спецификацию, терминальные реквизиты и сертификат.
  2. Для динамического JSON подписать запрос QRPAY и отправить на endpoint выбранного семейства; сохранить outTradeNo исходной операции, валюту и сумму платежа для последующего запроса QUERY.
  3. Для контроля отправлять QUERY со ссылкой на исходную операцию, проверять подпись ответа и повторять запрос до терминального статуса; не создавать новый платеж при неопределенном статусе.

Что проверить перед запуском

  • Не используйте URL агрегаторного endpoint для стандартного POS-протокола: публичная документация показывает разные hosts и наборы обязательных параметров.
  • Перед вычислением подписи сортируйте/собирайте поля в заданном протоколом порядке и приводите totalAmount к двум знакам после запятой.
  • SUCCESS при CANCEL во время подтверждения означает, что возврат будет запущен позже; это не всегда итоговый статус возврата.
О компании

Крупный российский банк, который предоставляет широкий спектр финансовых услуг. Он известен своими инновационными подходами и использованием современных технологий в обслуживании клиентов.

Связанные API