api/purchase-by-token - Оплата по токену карты

HTTP‑метод: POST
URL: /api/purchase-by-token
Форма взаимодействия: Сервер-сервер
Формат тела запроса: application/json
Назначение: проведение операции PURCHASE по токену ранее сохраненной карты.

URL

URLPATH

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

/api/purchase-by-token

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

Поле	Тип	Обяз.	Описание
`terminal`	`str`	✔	Уникальный идентификатор учетной записи ТСП в ПЦ.
`order_id`	`int`	✔	Уникальный идентификатор Заказа в ПЦ, полученный по результатам Запроса api/register.
`payer`	`object`	✔	Данные Плательщика. Обязательно вложенное поле `payment_mean_token` — токен ранее зарегистрированной Платёжной карты Плательщика. Позволяет Плательщику не вводить все реквизиты Карты при повторной оплате, но при этом поддерживает работу с 3DS. См. структуру payer/receiver.
`signature`	`str`	✔	Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.
Необязательные параметры
`cvc`	`str`		CVV2/CVC2. Для большей безопасности, у Плательщика может быть дополнительно запрошен код безопасности карты перед выполнением операции.
`originator`	`int`		ID Операции в ПЦ (Purchase, Authorize), на основании которой был получен токен карты. Наличие данного параметра увеличивает конверсию регулярных платежей и требуется при возникновении претензий со стороны Плательщиков.
`unique_key`	`str`		Уникальный ключ идемпотентности запроса.
`apple_payment_data`	`str`		JSON-объект в base64. Платежные данные Apple Pay (значение поля `paymentData` из `PKPaymentToken`). Имеет более высокий приоритет, чем `apple_payment_token`. Анализируется только вместе с `action=pay`.
`apple_payment_token`	`str`		JSON-объект с платёжными данными Apple Pay (объект класса `PKPaymentToken`). Анализируется только вместе с `action=pay`.
`google_cryptogram`	`str`		JSON-объект в base64. Платежные данные Google Pay (значение поля `cryptogram`, полученного от Google). Анализируется только вместе с `action=pay`.
`yandex_cryptogram`	`str`		JSON-объект в base64. Платежные данные Yandex Pay (значение поля `cryptogram`, полученного от Yandex). Анализируется только вместе с `action=pay`.
`samsung_ref_id`	`str`		Уникальный референс запроса на получение криптограммы карты Samsung Pay. Анализируется только вместе с `action=pay`.

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

Поле	Тип	Обяз.	Описание
`order_id`	`int`	✔	Идентификатор заказа в ПЦ. Пример: `1009982`
`order_status`	`str`	✔	Статус заказа. Пример: `REGISTERED`
`client_id`	`str`	✔	Номер заказа на стороне ТСП. Пример: `test`
`tx_id`	`int`	✔	Идентификатор операции в ПЦ. Пример: `5587788`
`tx_completed_at`	`datetime`	✔	Дата и время совершения операции в ПЦ (`YYYY.MM.DD HH:MM:SS`). Пример: `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`	✔	Сумма операции в минимальных единицах валюты (для RUB — копейки). Пример: `100`
`currency`	`int`	✔	Код валюты по ISO 4217 (643 — RUB, 978 — EUR, 840 — USD). Пример: `643`
`tx_approval_code`	`str`	✔	Код авторизации, полученный в Банке на данную операцию. Пример: `122004`
`signature`	`str`		Цифровая подпись сообщения. Пример: `8f2a1c9e3b7d4056a1f8c2e9d3b6a70158fce29b4d7a1e6c0938fa2d17bc45e9`

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

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

{
    "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",
    "signature": "8f2a1c9e3b7d4056a1f8c2e9d3b6a70158fce29b4d7a1e6c0938fa2d17bc45e9"
}

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

Примечания

Ответ не включает поля name, pan, email — данные карты/плательщика в ответе api/purchase-by-token не возвращаются.
Ответ может содержать ряд необязательных параметров, которые важно учесть при составлении подписи.