api/wallet/pay-in-sbp-by-token - Пополнение Кошелька через СБП-токен

HTTP‑метод: POST
URL: /api/wallet/pay-in-sbp-by-token
Форма взаимодействия: Сервер-сервер
Формат тела запроса: application/json
Назначение: пополнение Кошелька через безакцептное списание денежных средств с использованием ранее выпущенного СБП-токена.

URL

URLPATH

https://gateway-docs.wallet.kvell.group/api/wallet/pay-in-sbp-by-token

/api/wallet/pay-in-sbp-by-token

Структура запроса

Поле	Тип	Обяз.	Описание
`terminal`	`str`	✔	Уникальный идентификатор учетной записи ТСП в ПЦ.
`order_id`	`int`	✔	Уникальный идентификатор предварительно зарегистрированного Заказа в ПЦ, полученный по результатам `api/register`.
`payer`	`object`	✔	Данные Плательщика. Обязательно вложенное поле `payment_mean_token` — СБП-токен, полученный ТСП во время осуществления привязки через `pay-in-sbp-by-token` или `pay-in-sbp-qr-link` (см. структуру payer/receiver).
`signature`	`str`	✔	Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.
Необязательные параметры
`receiver`	`object`		Данные Кошелька-получателя. Значимое поле: `wallet_public_id`.
`unique_key`	`str`		Ключ уникальности запроса. Генерируется на стороне ТСП. При получении ключа ПЦ выполняет проверку на наличие дубликата среди обрабатываемых запросов и созданных операций. Формат: допустимы цифры `[0-9]`, латинские буквы `[a-zA-Z]`, дефис и нижнее подчёркивание `[-_]`.

Структура ответа

Поле	Тип	Обяз.	Описание
`order_id`	`int`	✔	Идентификатор заказа в ПЦ. Пример: `1234`
`order_status`	`str`	✔	Статус заказа. Пример: `COMPLETED`
`client_id`	`str`		Идентификатор пользователя ТСП. Пример: `test`
`tx_id`	`int`	✔	Идентификатор операции в ПЦ. Пример: `5587788`
`tx_completed_at`	`datetime`	✔	Дата и время совершения операции в ПЦ. Пример: `2024.01.28 00:23:19`
`tx_type`	`str`	✔	Тип операции. Пример: `PURCHASE_BY_QR`
`tx_status`	`str`	✔	Статус операции. Пример: `APPROVED`
`amount`	`int`	✔	Сумма операции в минимальных единицах валюты. Пример: `10000`
`fee`	`int`	✔	Сумма комиссии в минимальных единицах валюты. Пример: `0`
`currency`	`int`	✔	Код валюты по ISO4217. Пример: `643`
`unique_key`	`str`		Ключ уникальности запроса. Пример: `test2`
`receiver_wallet_public_id`	`str`	✔	Уникальный идентификатор Кошелька. Пример: `zzz`
`terminal_id`	`str`	✔	Уникальный идентификатор учётной записи ТСП в ПЦ. Пример: `823`
`payment_system`	`str`	✔	Платёжная система. Пример: `2`
`ofd_link`	`str`		Ссылка на фискальный чек. Пример: `https://ofd-link.ru/ofd/get-receipt?terminal=123325425345&tx_id=141&signature=...`
`qr_link`	`str`		НСПК-ссылка для проведения оплаты. Пример: `https://qr.nspk.ru/AD10005F3ED994U?type=02&bank=100030&sum=1000&cur=RUB&crc=A479`
`qrc_id`	`str`		Идентификатор транзакции QR. Пример: `AD10005F3ED9GCLM94U`
`sbp_tran_id`	`str`		Идентификатор транзакции СБП. Пример: `asdghwerydfhsjkdhfuwoijkk`
`payer_public_id`	`str`	✔	Идентификатор плательщика. Пример: `*********0000`
`signature`	`str`		Цифровая подпись сообщения.

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

Успех (200)Пример ошибки (404)

{
    "order_id": 1234,
    "order_status": "COMPLETED",
    "client_id": "test",
    "tx_id": 5587788,
    "tx_completed_at": "2024.01.28 00:23:19",
    "tx_type": "PURCHASE_BY_QR",
    "tx_status": "APPROVED",
    "amount": 10000,
    "fee": 0,
    "currency": 643,
    "unique_key": "test2",
    "receiver_wallet_public_id": "zzz",
    "terminal_id": "823",
    "payment_system": "2",
    "ofd_link": "https://ofd-link.ru/ofd/get-receipt?terminal=123325425345&tx_id=141&signature=ZjY1YTlkM2Y4NGE3N2M2NTVhYzFlZmVkMTgzYmI0YTY1MTAxYjI4ZGMwMTZkNTNiMDFjNmU1N2IwZjBiZDlmZQ%3D%3D",
    "qr_link": "https://qr.nspk.ru/AD10005F3ED994U?type=02&bank=100030&sum=1000&cur=RUB&crc=A479",
    "qrc_id": "AD10005F3ED9GCLM94U",
    "sbp_tran_id": "asdghwerydfhsjkdhfuwoijkk",
    "payer_public_id": "*********0000",
    "signature": "6b0d3f81a5c9e247b0d15f7a3c9e6021b4d7f0a2c5e8913f6b0d4a7c2e58f19"
}

{
    "error_code": "TERMINAL_NOT_FOUND",
    "technical_message": "Terminal not found",
    "timestamp": 1751976000,
    "details": null,
    "request_id": "b3b3c1f0-4b3a-4f3a-9b1a-1234567890ab"
}

Примечания

При получении запроса ПЦ проверяет:
Если в запросе передан параметр unique_key, то ПЦ проверяет запрос на наличие дубля;
Правильность расчета подписи и корректность параметров запроса;
Принадлежность к терминалу и валидность переданного в запросе СБП-токена;
Если в запросе указан receiver.wallet_public_id, который ранее уже был зарегистрирован для терминала, зачисление средств по операции, выполненной с использованием предоставленного токена, будет проводиться на баланс этого ранее зарегистрированного Кошелька. Иначе будет создан и пополнен новый Кошелёк.