Т‑Касса: Отменить платеж или вернуть деньги

Сценарий из mcp-everything. Актуально на 2026-10-12.

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

Вызови POST /v2/GetState и определи текущий статус платежа.
Для полной операции вызови POST /v2/Cancel без Amount; для частичной передай сумму возврата в Amount.
Если при частичной операции подключена онлайн-касса, передай в Receipt возвращаемые позиции; при полной операции Receipt не передавай.
Проверь результат через уведомление или 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>"
  }'

Базовые URL

Боевой: https://securepay.tinkoff.ru/v2
Тестовый: https://rest-api-test.tinkoff.ru/v2

Авторизация

Тип: Другое

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

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

Методы сценария

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/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 с JSON; имена методов и параметров чувствительны к регистру. Передавай Content-Type: application/json и используй TLS 1.2 или выше.
Суммы передаются в копейках, интернет-эквайринг принимает оплату только в рублях. В POST /v2/Init сумма Amount должна совпадать с суммой Receipt.Items.Amount.
HTTP 200 не гарантирует успех операции: проверяй Success, ErrorCode и Status. OpenAPI описывает успешный и ошибочный ответ как варианты одного ответа 200.
Не включай в расчет Token вложенные объекты и массивы, в том числе DATA и Receipt. Password добавляется только при расчете подписи и не отправляется.
Не считай редирект на SuccessURL подтверждением оплаты. Проверь уведомление или POST /v2/GetState и обязательно сравни Amount с ожидаемой суммой заказа.
Перед обработкой уведомления проверь его Token. Ответ должен быть HTTP 200 с телом OK заглавными английскими буквами; ожидание ответа — 10 секунд.
Если OK не получен, уведомление повторяется раз в час в течение 24 часов, затем раз в сутки в течение месяца. Архив уведомлений хранится 90 дней.
Для двухстадийной оплаты POST /v2/Confirm вызывается только в статусе AUTHORIZED; подтвердить карточный платеж нужно в течение 7 дней, включая день авторизации.
Возможность платежей по сохраненным реквизитам по умолчанию выключена. RebillId нужно брать только из проверенного уведомления родительского платежа.
Тестовая среда требует добавления IP в белый список. Для нее используется боевой терминал без приставки DEMO; тест-кейсы с DEMO-терминалом, наоборот, отправляются на боевой URL.

Другие сценарии

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