api/wallet/pay-out-sbp-precheck - Проверка возможности СБП-выплаты

HTTP‑метод: POST
URL: /api/wallet/pay-out-sbp-precheck
Форма взаимодействия: Сервер-сервер
Формат тела запроса: application/json
Назначение: проверка возможности совершения СБП-выплаты со счета Кошелька по номеру телефона.

URL

URLPATH

https://gateway-docs.wallet.kvell.group/api/wallet/pay-out-sbp-precheck

/api/wallet/pay-out-sbp-precheck

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

Поле	Тип	Обяз.	Описание
`terminal`	`str`	✔	Уникальный идентификатор учетной записи ТСП в ПЦ.
`payer`	`object`	✔	Данные Кошелька-отправителя. Обязательно вложенное поле `wallet_public_id` (см. структуру payer/receiver). Если было объявлено, то ПЦ проверит, достаточно ли денежных средств для вывода с Кошелька на данный момент. Важно: параметр должен быть передан при регистрации заказа (`api/register`).
`signature`	`str`	✔	Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.
Условно‑обязательные параметры
`receiver`	`object`		Данные Получателя. Значимые поля: `phone`, `bank_id`, `payment_mean_token`. Указывать либо `phone` и `bank_id`, либо `payment_mean_token`.
`amount`	`int`		Сумма операции в минимальных единицах валюты. Для рублей — копейки. Обязателен, если не указан `order_id` (тогда значение берётся из заказа).
`currency`	`int`		Код валюты по ISO4217 (643 для RUB; 978 для EUR; 840 для USD). Обязателен, если не указан `order_id` (тогда значение берётся из заказа).
`description`	`str`		Описание перевода. Обязателен, если не указан `order_id` (тогда значение берётся из заказа).
`fee`	`int`		Комиссия за осуществление выплаты в минимальных единицах валюты. Для рублей — копейки. Обязателен, если не указан `order_id` (тогда значение берётся из заказа).
Необязательные параметры
`order_id`	`int`		Уникальный идентификатор платежа (Заказа) в ПЦ, полученный по результатам запроса `api/register`.
`tx_client_id`	`str`		Номер перевода на стороне Площадки. Если не указан, значение формируется автоматически на стороне ПЦ. Если в запросе указан параметр `order_id`, значение `tx_client_id` из запроса игнорируется.

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

Поле	Тип	Обяз.	Описание
`precheck_tx_id`	`str`	✔	Идентификатор проверки. Пример: `730211959044920001`
`order_id`	`int`	✔	Идентификатор заказа в ПЦ. Пример: `471556`
`amount`	`int`	✔	Сумма операции. Пример: `10000`
`recipient_bank_id`	`str`		Идентификатор банка получателя. Пример: `1crt88888881`
`pam`	`str`		ФИО получателя. Пример: `Петр Петрович П`
`ref`	`str`	✔	Идентификатор Кошелька. Пример: `471554`
`signature`	`str`		Цифровая подпись ответа ПЦ.

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

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

{
    "precheck_tx_id": "730211959044920001",
    "order_id": 471556,
    "amount": 10000,
    "recipient_bank_id": "1crt88888881",
    "pam": "Петр Петрович П",
    "ref": "471554",
    "signature": "8f2a1c9e3b7d4056a1f8c2e9d3b6a70158fce29b4d7a1e6c0938fa2d17bc45e9"
}

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

Примечания

При получении запроса ПЦ проверяет:
Правильность расчета подписи и корректность параметров запроса;
Наличие разрешения терминала на использование сервиса;
Обязательно указание либо пары receiver.phone + receiver.bank_id, либо receiver.payment_mean_token — иначе ошибка валидации поля receiver.phone ("require receiver.phone and receiver.bank_id, or receiver.payment_mean_token");
Наличие на балансе Кошелька денежных средств в размере суммы значений параметров amount и fee, переданных в запросе или объявленных в Заказе с переданным order_id.
Поле precheck_tx_id из ответа этого метода нужно передать как precheck_tx_id в последующий запрос api/wallet/pay-out-sbp.