Т‑Касса API

Отрасль: Платежи и финансы. Актуально на 2026-10-12.

API интернет-эквайринга Т‑Бизнеса для приема онлайн-платежей, двухстадийного списания, возвратов и платежей по сохраненным реквизитам. Основной поток строится вокруг платежа: POST /v2/Init создает его, покупатель оплачивает на форме Т‑Банка, а магазин получает результат через HTTP(S)-уведомление или POST /v2/GetState.

Охват

Есть:

Нет — смотри официальную документацию:

Сценарии

Принять одностадийную оплату

Подходит для заказа, деньги за который нужно списать сразу после оплаты покупателем. Результат — платеж в статусе CONFIRMED, сверенный с суммой заказа.

  1. Подключи интернет-эквайринг, создай магазин и терминал в личном кабинете Т‑Бизнеса; возьми TerminalKey и Password.
  2. Сформируй Token и вызови POST /v2/Init с Amount в копейках, уникальным OrderId и при необходимости PayType=O.
  3. Перенаправь покупателя на PaymentURL из ответа POST /v2/Init.
  4. Прими POST-уведомление на NotificationURL, проверь его Token, PaymentId, Amount и статус; при успешной обработке ответь HTTP 200 с телом OK.
  5. Если уведомление не получено, вызови POST /v2/GetState; выдавай товар только после сверки Amount и статуса CONFIRMED.
curl --request POST 'https://securepay.tinkoff.ru/v2/Init' \
  --header 'Content-Type: application/json' \
  --data '{
    "TerminalKey": "<TerminalKey>",
    "Amount": 140000,
    "OrderId": "21090",
    "Token": "<Token>",
    "PayType": "O",
    "DATA": {"OperationInitiatorType": "0"}
  }'

Провести двухстадийную оплату

Нужна, когда сначала следует заблокировать деньги, а списать их после проверки наличия или оказания услуги. Результат — перевод платежа из AUTHORIZED в CONFIRMED полностью или на меньшую сумму.

  1. Вызови POST /v2/Init с PayType=T и перенаправь покупателя на PaymentURL.
  2. Дождись уведомления или вызови POST /v2/GetState; продолжай только для платежа в статусе AUTHORIZED.
  3. В течение 7 дней, включая день авторизации, вызови POST /v2/Confirm. Для частичного списания передай Amount; если подключена онлайн-касса, передай Receipt.
  4. Дождись уведомления или проверь POST /v2/GetState: успешное списание имеет статус CONFIRMED.
curl --request POST 'https://securepay.tinkoff.ru/v2/Confirm' \
  --header 'Content-Type: application/json' \
  --data '{
    "TerminalKey": "<TerminalKey>",
    "PaymentId": "2304882",
    "Token": "<Token>",
    "Amount": 19200
  }'

Отменить платеж или вернуть деньги

Один метод снимает холд у платежа в AUTHORIZED и возвращает уже списанные деньги у платежа в CONFIRMED. Результирующий статус зависит от исходного состояния и полноты операции.

  1. Вызови POST /v2/GetState и определи текущий статус платежа.
  2. Для полной операции вызови POST /v2/Cancel без Amount; для частичной передай сумму возврата в Amount.
  3. Если при частичной операции подключена онлайн-касса, передай в Receipt возвращаемые позиции; при полной операции Receipt не передавай.
  4. Проверь результат через уведомление или POST /v2/GetState: PARTIAL_REVERSED/REVERSED означают отмену холда, PARTIAL_REFUNDED/REFUNDED — возврат списанных денег.
curl --request POST 'https://securepay.tinkoff.ru/v2/Cancel' \
  --header 'Content-Type: application/json' \
  --data '{
    "TerminalKey": "<TerminalKey>",
    "PaymentId": "2304882",
    "Token": "<Token>"
  }'

Списать по сохраненным реквизитам

Подходит для подписки или повторной оплаты без повторного ввода реквизитов. Сначала покупатель подтверждает родительский платеж, затем магазин использует полученный RebillId для дочерних платежей.

  1. Подключи платежи по сохраненным реквизитам: на DEMO-терминале через acq_help@tbank.ru, на боевом — через персонального менеджера.
  2. Создай родительский платеж через POST /v2/Init, передав Recurrent=Y, CustomerKey и DATA.OperationInitiatorType=1; перенаправь покупателя на PaymentURL.
  3. После успешной авторизации возьми RebillId из проверенного уведомления.
  4. Для дочернего платежа вызови POST /v2/Init с новой суммой и новым OrderId; для регулярного списания передай DATA.OperationInitiatorType=R.
  5. Не открывая полученный PaymentURL, вызови POST /v2/Charge с новым PaymentId и сохраненным RebillId.
  6. Проверь уведомление или вызови POST /v2/GetState; успешный одностадийный платеж завершится статусом CONFIRMED.
curl --request POST 'https://securepay.tinkoff.ru/v2/Charge' \
  --header 'Content-Type: application/json' \
  --data '{
    "TerminalKey": "<TerminalKey>",
    "PaymentId": "700001702044",
    "RebillId": "145919",
    "Token": "<Token>"
  }'

Восстановить статус платежа или заказа

Используй этот сценарий после таймаута, потери ответа или уведомления. Результат — состояние конкретного платежа либо список всех платежей, созданных для заказа.

  1. Если известен PaymentId, вызови POST /v2/GetState и сверь Amount, OrderId, Success, ErrorCode и Status.
  2. Если известен только OrderId или для заказа создавались повторные платежи, вызови POST /v2/CheckOrder.
  3. Выбери нужную запись из Payments ответа POST /v2/CheckOrder по PaymentId и обрабатывай ее текущий Status, не полагаясь только на редирект SuccessURL.
curl --request POST 'https://securepay.tinkoff.ru/v2/CheckOrder' \
  --header 'Content-Type: application/json' \
  --data '{
    "TerminalKey": "<TerminalKey>",
    "OrderId": "21057",
    "Token": "<Token>"
  }'

Базовые URL

Авторизация

Тип: Другое

Для каждого подписываемого запроса передавай TerminalKey и Token в корневом JSON-объекте. TerminalKey и секретный Password находятся в личном кабинете интернет-эквайринга; Password в запрос не передается.

Чтобы получить Token, собери корневые параметры запроса, добавь к ним Password, исключи Token, вложенные объекты и массивы, отсортируй пары по имени ключа, склей только значения и вычисли SHA-256 в UTF‑8. Полученную шестнадцатеричную строку передай в Token.

Методы

POST /v2/Init — Инициировать платеж

Создает платеж в статусе NEW и возвращает PaymentId; при использовании формы Т‑Банка также возвращает PaymentURL.

Документация: https://developer.tbank.ru/eacq/api/init

Параметр Где Тип Обяз. Описание
TerminalKey body string да Идентификатор терминала, до 64 символов
Amount body integer да Сумма в копейках
OrderId body string да Уникальный для каждой операции идентификатор заказа, до 50 символов
Token body string да Подпись запроса
Description body string нет Описание заказа на платежной форме
CustomerKey body string нет Идентификатор покупателя; обязателен для карточного платежа с Recurrent=Y
Recurrent body string нет Y для родительского платежа с сохранением реквизитов
PayType body string нет O — одностадийная, T — двухстадийная оплата
NotificationURL body string нет URL для POST-уведомлений
SuccessURL body string нет URL возврата покупателя после успешной оплаты
FailURL body string нет URL возврата покупателя после неуспешной оплаты
RedirectDueDate body string нет Срок жизни платежной ссылки
DATA.OperationInitiatorType body string нет Инициатор операции: 0, 1, 2, R, I, D или N
Receipt body object нет Данные чека; обязателен при подключенной онлайн-кассе

Пример ответа:

{
  "Success": true,
  "ErrorCode": "0",
  "TerminalKey": "TBankTest",
  "Status": "NEW",
  "PaymentId": "3093639567",
  "OrderId": "21090",
  "Amount": 140000,
  "PaymentURL": "https://pay.tbank.ru/new/fU1ppgqa"
}

POST /v2/Confirm — Подтвердить списание

Списывает всю или часть заблокированной суммы двухстадийного платежа. Метод применим только к платежу в статусе AUTHORIZED.

Документация: https://developer.tbank.ru/eacq/api/confirm

Параметр Где Тип Обяз. Описание
TerminalKey body string да Идентификатор терминала, до 64 символов
PaymentId body string да Идентификатор платежа, до 20 символов
Token body string да Подпись запроса
IP body string нет IP-адрес покупателя
Amount body integer нет Сумма списания в копейках; без поля используется исходная сумма
Receipt body object нет Данные чека; обязателен при подключенной онлайн-кассе

POST /v2/Cancel — Отменить платеж

Отменяет авторизованный платеж либо возвращает подтвержденный платеж. Без Amount выполняется полная операция; в статусе NEW значение Amount игнорируется.

Документация: https://developer.tbank.ru/eacq/api/cancel

Параметр Где Тип Обяз. Описание
TerminalKey body string да Идентификатор терминала, до 64 символов
PaymentId body string да Идентификатор платежа
Token body string да Подпись запроса
IP body string нет IP-адрес покупателя
Amount body integer нет Сумма частичной отмены или возврата в копейках
Receipt body object нет Возвращаемые позиции; обязателен при частичной операции с онлайн-кассой
QrMemberId body string нет Код банка СБП для возврата в другой банк
ExternalRequestId body string нет Ключ идемпотентности; обязателен для «Долями» и рассрочки

POST /v2/Charge — Провести платеж по сохраненным реквизитам

Проводит дочернюю COF-операцию по ранее полученному RebillId. Перед вызовом нужно создать новый платеж через POST /v2/Init и использовать его PaymentId.

Документация: https://developer.tbank.ru/eacq/api/charge

Параметр Где Тип Обяз. Описание
TerminalKey body string да Идентификатор терминала, до 64 символов
PaymentId body string да Идентификатор нового платежа, до 20 символов
RebillId body string да Идентификатор сохраненных платежных реквизитов из уведомления
Token body string да Подпись запроса
IP body string нет IP-адрес покупателя
SendEmail body boolean нет Отправлять уведомление об оплате на почту
InfoEmail body string нет Почта покупателя; обязательна при SendEmail=true

POST /v2/GetState — Получить статус платежа

Возвращает сумму, заказ и текущий статус конкретного платежа.

Документация: https://developer.tbank.ru/eacq/api/get-state

Параметр Где Тип Обяз. Описание
TerminalKey body string да Идентификатор терминала, до 64 символов
PaymentId body string да Идентификатор платежа, до 20 символов
Token body string да Подпись запроса
IP body string нет IP-адрес покупателя
GetPhone body boolean нет Запросить номер телефона

POST /v2/CheckOrder — Получить статус заказа

Возвращает массив Payments с историей и текущими статусами платежей для одного заказа.

Документация: https://developer.tbank.ru/eacq/api/check-order

Параметр Где Тип Обяз. Описание
TerminalKey body string да Идентификатор терминала, до 64 символов
OrderId body string да Идентификатор заказа, до 50 символов
Token body string да Подпись запроса

Нюансы

Ошибки

Код Описание
0 None
2 Отсутствуют обязательные параметры
20 Ошибка повторного идентификатора заказа
50 Ошибка отправки нотификации
202 Терминал заблокирован
204 Неверный токен. Проверьте пару TerminalKeySecretKey
251 Неверная сумма. Сумма должна быть больше или равна {value} копеек
255 Платеж не найден
3002 Недостаточный баланс счета для отмены
9999 Внутренняя ошибка системы

Ограничения

Источники

Если этого недостаточно — официальная документация: https://developer.tbank.ru/eacq/intro/ JSON: https://mcp-everything.ru/api/integrations/t-kassa-api. MCP: https://mcp-everything.ru/mcp