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

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

- HTML: https://poapi.ru/t-bank/tacap-api
- Компания: Т-Банк
- Страница компании: https://poapi.ru/company/t-bank
- Категории: Финансы
- Сайт API: https://developer.tbank.ru/tacap/api
- Адрес API: https://qrpay.tinkoff.ru/qrpay/external/api/v1/operations
- Документация: https://developer.tbank.ru/tacap/api

## Подключение и ограничения
- Авторизация: Обычный 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 нужно сверять для выбранной интеграции.

```bash
# Только чтение статуса ранее созданной операции; замените значения параметрами 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 сверяйте отдельно: промежуточный ответ не является основанием создать новый платёж.
- Проверено по документации: 2026-11-02
- Источник: https://developer.tbank.ru/tacap/api
- Источник: https://developer.tbank.ru/tacap/api/tacap-api
- Источник: https://developer.tbank.ru/tacap/api/torgovie-operatsii-s-dinamicheskim-qr-kodom-json
- Источник: https://developer.tbank.ru/tacap/api/query-json
- Источник: https://developer.tbank.ru/tacap/api/qrpay-json

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

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

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

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

## Связанные API
- [Торговый эквайринг Т-Банка](https://poapi.ru/t-bank/torgovyy-ekvayring): Получайте список активных POS терминалов компании и запрашивайте карточные операции по серийному номеру терминала за период.
