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

api/wallet/pay-in-debit - Списание средств с карты Плательщика

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

URL

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

1
/api/wallet/pay-in-debit

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

Поле Тип Обяз. Описание
terminal str ✔ Уникальный идентификатор учетной записи ТСП в ПЦ.
signature str ✔ Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.
Условно‑обязательные параметры
amount int Сумма операции в минимальных единицах валюты. Для рублей — копейки. Обязателен, если не указан order_id (тогда значение берётся из заказа).
description str Описание перевода. Обязателен, если не указан order_id (тогда значение берётся из заказа).
currency int Код валюты по ISO4217 (643 для RUB; 978 для EUR; 840 для USD). Обязателен, если не указан order_id (тогда значение берётся из заказа).
Необязательные параметры
order_id int Уникальный идентификатор предварительно зарегистрированного Заказа в ПЦ, полученный по результатам api/register.
receiver object Данные получателя чаевых. Значимые поля (см. структуру payer/receiver): wallet_public_id, payment_mean_token — токен карты получателя чаевых, public_id — идентификатор пользователя-получателя чаевых.
unique_key str Ключ уникальности запроса. Генерируется на стороне ТСП. При получении ключа ПЦ выполняет проверку на наличие дубликата среди обрабатываемых запросов и созданных операций. Формат: допустимы цифры [0-9], латинские буквы [a-zA-Z], дефис и нижнее подчёркивание [-_].
tips int Сумма чаевых в минимальных единицах валюты. Не может превышать amount.
payer object Данные Плательщика. Значимые поля (см. структуру payer/receiver): payment_mean_token — токен ранее зарегистрированной карты Плательщика, заменяющий карту Плательщика (позволяет не вводить реквизиты карты при повторном переводе); public_id — идентификатор пользователя Площадки, для которого будет запомнена карта плательщика (если указан payment_mean_token, значение public_id не используется).
is_get_token int Запрос на предоставление токена карты, использованной в операции, в составе уведомления на url. Возможные значения: 0 (по умолчанию) — не возвращать; 1 — вернуть токен.
cvc str Проверочный код карты Плательщика CVV2/CVC2/ППК2.
fee int Комиссия для удержания с Плательщика при списании средств с его карты в минимальных единицах валюты.
action str Если action=pay, ПЦ пытается провести операцию на основании параметров запроса без отображения платёжной формы. При нехватке данных отображается форма для заполнения.
tx_client_id str Номер перевода на стороне ТСП (в ИС ТСП).
return_url str Адрес страницы на стороне ТСП, на которую автоматически переводится Плательщик по завершении операции.
fail_url str Адрес страницы на стороне ТСП, на которую автоматически переводится Плательщик в случае неуспешного окончания операции.
apple_payment_data str (base64) Платёжные данные Apple Pay в виде base64‑кодированной строки JSON (значение paymentData платёжного токена Apple). Приоритетнее apple_payment_token. Анализируется только вместе с action=pay.
apple_payment_token str Платёжный токен Apple Pay (PKPaymentToken). Анализируется только вместе с action=pay.
google_cryptogram str (base64) Платёжные данные Google Pay в виде base64‑кодированной строки JSON (поле cryptogram). Анализируется только вместе с action=pay.
yandex_cryptogram str (base64) Платёжные данные Yandex Pay в виде base64‑кодированной строки JSON (поле cryptogram). Анализируется только вместе с action=pay.
samsung_ref_id str Платёжные данные Samsung Pay: уникальный референс запроса на получение криптограммы карты. Анализируется только вместе с action=pay.

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

Этот эндпоинт не возвращает JSON-тело. При успешной валидации запроса ПЦ создаёт транзакцию и отвечает HTTP 303 See Other с redirect (заголовок Location) на платёжную форму (form_link), сформированную ПЦ:

  • если return_url / fail_url не заполнены — Плательщик увидит экранную платёжную форму / экранный чек ПЦ;
  • если return_url / fail_url заполнены — после завершения операции на платёжной форме ПЦ выполнит стандартный redirect на return_url / fail_url (в зависимости от результата) с присоединением информации об операции в виде GET‑параметров.

На адрес URL‑уведомлений, указанный в ЛК Площадки, ПЦ отправляет уведомление с параметрами совершённой операции.

При ошибке валидации запроса (до создания транзакции) ПЦ отвечает обычным JSON-телом ошибки (см. ниже) вместо редиректа.

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

HTTP/1.1 303 See Other
Location: https://<ПЦ>/payment/form?order_id=1009982&...

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

Примечания

  • В результате успешного прохождения операции оплаты средства будут сразу списаны с карты пользователя. Холдирование не предусмотрено. Операция complete является опциональной.
  • Если order_id не указан, обязательны amount, description и currency — они берутся из тела запроса, а не из заказа (валидируется model_validator на стороне ПЦ).
  • Если tips указан вместе с amount и превышает его, запрос отклоняется с ошибкой валидации поля tips.
  • Если в запросе передан payer.payment_mean_token, значение payer.public_id игнорируется (не используется) независимо от того, что было передано.