api/wallet/purchase - Перечисление средств со счета Кошелька

HTTP‑метод: POST
URL: /api/wallet/purchase
Форма взаимодействия: Сервер-сервер
Формат тела запроса: application/json
Назначение: перечисление средств со счета Кошелька в пользу юридического лица, либо для выполнения перевода по реквизитам счета.

В случае затруднений с заполнением полей для платежа по свободным реквизитам, ориентируйтесь на правила заполнения платежного поручения. Названия параметров этого блока идентичны названиям полей платежного поручения.

Предупреждение: перед выполнением запроса рекомендуется зарегистрировать в ПЦ Заказ с описанием всех деталей предстоящего платежа. Сделайте это отдельным запросом api/register.

URL

URLPATH

https://gateway-docs.wallet.kvell.group/api/wallet/purchase

/api/wallet/purchase

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

Поле	Тип	Обяз.	Описание
`terminal`	`str`	✔	Уникальный идентификатор учетной записи ТСП в ПЦ.
`payer`	`object`	✔	Данные Кошелька/Плательщика (см. структуру payer/receiver). Обязательно вложенное поле `wallet_public_id`. Прочие значимые поля: `email` (если указан `order_id`, значение игнорируется и берётся из заказа), `phone`, `country`, `region`, `bank_name`, `first_name`, `last_name`, `middle_name`, `receipt_type`.
`signature`	`str`	✔	Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.
Условно‑обязательные параметры
`amount`	`int`		Сумма операции в минимальных единицах валюты. Для рублей — копейки. Обязателен, если не указан `order_id` (тогда значение берётся из заказа).
`currency`	`int`		Код валюты по ISO4217 (643 для RUB; 978 для EUR; 840 для USD). Обязателен, если не указан `order_id` (тогда значение берётся из заказа).
`description`	`str`		Описание перевода. Обязателен, если не указан `order_id` (тогда значение берётся из заказа).
Необязательные параметры
`order_client_id`	`str`		Номер Заказа на стороне ТСП (в ИС ТСП).
`order_id`	`int`		Уникальный идентификатор предварительно зарегистрированного Заказа в ПЦ.
`unique_key`	`str`		Ключ уникальности запроса. Генерируется на стороне ТСП. При получении ключа ПЦ выполняет проверку на наличие дубликата среди обрабатываемых запросов и созданных операций. Формат: допустимы цифры `[0-9]`, латинские буквы `[a-zA-Z]`, дефис и нижнее подчёркивание `[-_]`.
`fio`	`str`		Фамилия Имя Отчество получателя денежных средств.
`receiver`	`object`		Данные получателя денежных средств. Значимые поля: `acc_number`, `contract`.
`free_requisites`	`object`		Набор свободных реквизитов для платежа по свободным реквизитам (см. ниже).

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

Поле	Тип	Описание
`p008_1`	`str`	Наименование Плательщика.
`p008_2`	`str`	Адрес Плательщика.
`P014`	`str`	БИК получателя (ровно 9 цифр).
`P015`	`str`	Корр. счёт банка получателя (ровно 20 цифр).
`P016`	`str`	Наименование Получателя.
`P017`	`str`	Счет получателя (ровно 20 цифр).
`P018`	`str`	Вид операции. Возможные значения: 01 — платежное поручение; 06 — инкассовое поручение; 02 — платежное требование.
`P020`	`str`	Назначение платежа. Заполняется при указании банка.
`P021`	`str`	Очередность платежа.
`P022`	`str`	УИН (20 или 25 цифр). Если отсутствует — проставьте 0.
`P024`	`str`	Назначение платежа.
`P060`	`str`	ИНН Плательщика (10 или 12 цифр). Если отсутствует — проставьте 0.
`P061`	`str`	ИНН Получателя (10 или 12 цифр). Если отсутствует — проставьте 0.
`P101`	`str`	Статус Плательщика.
`P102`	`str`	КПП Плательщика (9 цифр). Если отсутствует — проставьте 0.
`P103`	`str`	КПП Получателя (9 цифр). Если отсутствует — проставьте 0.
`P104`	`str`	КБК Получателя.
`P105`	`str`	ОКТМО (8 или 11 цифр).
`P106`	`str`	Основание платежа.
`P107`	`str`	Налоговый период.
`P108`	`str`	Номер документа, который является основанием платежа, либо 0.
`P109`	`str`	Дата документа (формат `yyyy.MM.dd`). Если отсутствует — проставьте 0.
`P110`	`str`	Тип документа.

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

Поле	Тип	Обяз.	Описание
`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`		Цифровая подпись сообщения.

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

Успех (200)Пример ошибки (404)Дубликат unique_key (409)

{
    "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",
        "tx_status": "APPROVED",
        "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, то ПЦ проверяет запрос на наличие дубля (см. пример «Дубликат unique_key» выше);
Правильность расчета подписи и корректность параметров запроса;
payer.wallet_public_id должен быть ранее зарегистрирован для данного терминала;
Сумма параметров amount + fee, указанных в запросе, не должна превышать сумму текущего баланса Кошелька, идентификатор которого указан в параметре payer.wallet_public_id.
По окончании работы сервиса:
В случае успешной операции заказ переводится в статус COMPLETED;
Доступный баланс Кошелька payer.wallet_public_id уменьшается на сумму amount + fee.