Интегрируйте 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 сверяйте отдельно: промежуточный ответ не является основанием создать новый платёж.
Сверено с документацией: .
Порядок интеграции
- Уточнить тип подключения (кассовый или динамический QR; JSON/XML; агрегатор или устройство) и получить соответствующую спецификацию, терминальные реквизиты и сертификат.
- Для динамического JSON подписать запрос QRPAY и отправить на endpoint выбранного семейства; сохранить outTradeNo исходной операции, валюту и сумму платежа для последующего запроса QUERY.
- Для контроля отправлять QUERY со ссылкой на исходную операцию, проверять подпись ответа и повторять запрос до терминального статуса; не создавать новый платеж при неопределенном статусе.
Что проверить перед запуском
- Не используйте URL агрегаторного endpoint для стандартного POS-протокола: публичная документация показывает разные hosts и наборы обязательных параметров.
- Перед вычислением подписи сортируйте/собирайте поля в заданном протоколом порядке и приводите totalAmount к двум знакам после запятой.
- SUCCESS при CANCEL во время подтверждения означает, что возврат будет запущен позже; это не всегда итоговый статус возврата.
Крупный российский банк, который предоставляет широкий спектр финансовых услуг. Он известен своими инновационными подходами и использованием современных технологий в обслуживании клиентов.