Перейти к содержанию

api/wallet/pay-out - Выплата средств со счета Кошелька

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

URL

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

1
/api/wallet/pay-out

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

Поле Тип Обяз. Описание
terminal str ✔ Уникальный идентификатор учетной записи ТСП в ПЦ.
signature str ✔ Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.
payer object ✔ Данные Кошелька-отправителя. Обязательно вложенное поле wallet_public_id (см. структуру payer/receiver).
Условно‑обязательные параметры
amount int Сумма операции в минимальных единицах валюты. Для рублей — копейки. Обязателен, если не указан order_id (тогда значение берётся из заказа).
currency int Код валюты по ISO4217 (643 для RUB; 978 для EUR; 840 для USD). Обязателен, если не указан order_id (тогда значение берётся из заказа).
description str Описание перевода. Обязателен, если не указан order_id (тогда значение берётся из заказа).
receiver object Данные получателя средств. Значимые поля (см. структуру payer/receiver): payment_mean_token — токен карты получателя средств, обязателен, если не указано pan; pan — номер карты получателя, обязателен, если не указан payment_mean_token; public_id — идентификатор пользователя ТСП, которому переводятся средства.
Необязательные параметры
order_id int Уникальный идентификатор предварительно зарегистрированного Заказа в ПЦ.
unique_key str Ключ уникальности запроса. Генерируется на стороне ТСП. При получении ключа ПЦ выполняет проверку на наличие дубликата среди обрабатываемых запросов и созданных операций. Формат: допустимы цифры [0-9], латинские буквы [a-zA-Z], дефис и нижнее подчёркивание [-_].
order_client_id str Номер Заказа на стороне ТСП (в ИС ТСП).
fee int Комиссия для удержания с ТСП при списании средств с его технического счета в минимальных единицах валюты. Для рублей — копейки.
customers_stock object Мульти-зачисления (нескольким разным мерчантам), вложенный JSON-объект (см. ниже). Включает общую сумму мульти-зачисления и список пар wallet_public_id и amount, где требуется перевести мерчанту сумму, определённую параметром amount.

Вложенный объект customers_stock

Поле Тип Обяз. Описание
amount_shared int ✔ Общая сумма мульти-зачисления. Должна равняться сумме amount по всем элементам shares.
shares list[object] ✔ Список пар wallet_public_id/amount (см. ниже).

Элемент shares[]

Поле Тип Обяз. Описание
wallet_public_id str ✔ Уникальный идентификатор Кошелька-получателя доли.
amount int ✔ Сумма, зачисляемая на данный Кошелёк.

Пример:

{
    "amount_shared": 300,
    "shares": [
        {"wallet_public_id": "a1b2c3", "amount": 100},
        {"wallet_public_id": "d4e5f6", "amount": 200}
    ]
}

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

Поле Тип Обяз. Описание
order_id int ✔ Идентификатор заказа в ПЦ. Пример: 1009982
order_status str ✔ Статус заказа. Пример: REGISTERED
client_id str Идентификатор пользователя ТСП. Пример: test
tx_id int ✔ Идентификатор операции в ПЦ. Пример: 5587788
tx_completed_at datetime ✔ Дата и время совершения операции в ПЦ. Пример: 2024.01.28 00:23:19
tx_type str ✔ Тип операции. Пример: P2PTRANSFER
tx_status str ✔ Статус операции. Пример: APPROVED
tx_reason_code int ✔ Код ответа на операцию ПЦ. Пример: 1
message str Краткое описание кода ответа на операцию ПЦ. Пример: Successful financial transaction
amount int ✔ Сумма операции в минимальных единицах валюты. Пример: 100
currency int Код валюты по ISO4217. Пример: 643
tx_approval_code str ✔ Код авторизации, полученный в Банке на данную операцию. Пример: 122004
terminal_id str ✔ Уникальный идентификатор учётной записи ТСП в ПЦ. Пример: 893
bin_issuer str Идентификационный номер банка-Эмитента. Пример: JOINT STOCK COMMERCIAL BANK MOSCOW INDUSTRIAL BANK
expdate str Дата истечения срока действия карты. Пример: 10/2024
iso int Код валюты по ISO4217. Пример: 643
payment_system str ✔ Платёжная система. Пример: 2
rrn str ✔ RRN банковской транзакции. Пример: 33147812
bank_terminal_id str ✔ Идентификатор банковского терминала. Пример: POS_1
ofd_state str ✔ Статус обработки платежа онлайн-кассой. Пример: APPROVED
receiver_public_id str Идентификатор получателя денежных средств. Пример: 3a2dc480-659d-4b97-a5ac-bc35b2bcbc6e
payer_token str Токен карты плательщика. Пример: test
signature str Цифровая подпись сообщения.

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

{
    "order_id": 1009982,
    "order_status": "REGISTERED",
    "client_id": "test",
    "tx_id": 5587788,
    "tx_completed_at": "2024.01.28 00:23:19",
    "tx_type": "P2PTRANSFER",
    "tx_status": "APPROVED",
    "tx_reason_code": 1,
    "message": "Successful financial transaction",
    "amount": 100,
    "currency": 643,
    "tx_approval_code": "122004",
    "terminal_id": "893",
    "bin_issuer": "JOINT STOCK COMMERCIAL BANK MOSCOW INDUSTRIAL BANK",
    "expdate": "10/2024",
    "iso": 643,
    "payment_system": "2",
    "rrn": "33147812",
    "bank_terminal_id": "POS_1",
    "ofd_state": "APPROVED",
    "receiver_public_id": "3a2dc480-659d-4b97-a5ac-bc35b2bcbc6e",
    "payer_token": "test",
    "signature": "8f2a1c9e3b7d4056a1f8c2e9d3b6a70158fce29b4d7a1e6c0938fa2d17bc45e9"
}

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

{
    "duplicated_operation": {
        "unique_key": "test2",
        "tx_id": 449800,
        "tx_type": "PURCHASE_BY_QR",
        "tx_status": "COMPLETE",
        "order_id": 480413,
        "client_id": "721716fc-6837-4dbc-8308-37de445c30f0"
    },
    "code": "DUPLICATE_UNIQUE_KEY",
    "description": "Another request with unique key is in progress",
    "signature": "1a4f9c02e7b3d685f0a219c4e7b03d58f61ca2e9b7d0143f5a8c62e9d0b7415"
}

Примечания

  • При получении запроса ПЦ проверяет:
  • Если в запросе передан параметр unique_key, то ПЦ проверяет запрос на наличие дубля;
  • Правильность расчета подписи и корректность параметров запроса;
  • payer.wallet_public_id должен быть ранее зарегистрирован для данного терминала;
  • Должен быть указан хотя бы один из параметров receiver.payment_mean_token или receiver.pan (иначе — ошибка валидации: "receiver.pan or receiver.payment_mean_token required");

  • Сумма параметров amount + fee, указанных в запросе, не должна превышать сумму текущего баланса Кошелька, идентификатор которого указан в параметре payer.wallet_public_id.

  • По окончании работы сервиса:

  • В случае успешной операции заказ переводится в статус COMPLETED;

  • Доступный баланс Кошелька payer.wallet_public_id уменьшается на сумму amount + fee.

  • При получении в запросе параметра customers_stock:

  • Если в запросе также передан параметр receiver.public_id, то приоритет отдается параметру customers_stock, происходит мульти-выплата;
  • Некорректная структура customers_stock приводит к ошибке валидации поля customers_stock.