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

Gateway API

api/order

api/order - Получение информации по заказу

HTTP‑метод: POST, GET
URL: /api/order
Форма взаимодействия: Сервер-сервер
Формат тела запроса: application/json (для GET — query-параметры)
Назначение: получение информации по конкретному заказу.

URL

URLPATH

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

/api/order

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

Поле	Тип	Обяз.	Описание
`terminal`	`str`	✔	Уникальный идентификатор учетной записи ТСП в ПЦ.
`signature`	`str`	✔	Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.
Необязательные параметры
`order_id`	`int`		Уникальный идентификатор Заказа в ПЦ, полученный по результатам Запроса api/register.
`client_id`	`str`		Номер заказа на стороне ТСП в его Системе магазина. Если указан параметр client_id, но не указан order_id, то система ищет в ПЦ последний Заказ с указанным client_id в рамках client_id соответствующего терминала и выдает json с данными найденного Заказа. Если одновременно указаны и order_id, и client_id, то поиск Заказа идет по значению параметра order_id.
`mode`	`int`		Возможные значения: 0, 1. Если параметр mode=1, то ПЦ возвращает сокращённую информацию только по Заказу, без информации по каждой операции Заказа. (по умолчанию `0`)
`get_token`	`int`		Запрос на предоставление токена использованной в Операции Платёжной карты в составе уведомления на url. Возможные значения: 0 (по умолчанию), 1. 0 — токен не возвращать; 1 — вернуть токен. (по умолчанию `0`)

Валидация: либо order_id, либо client_id должно быть заполнено.

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

Поле	Тип	Обяз.	Описание
`id`	`int`	✔	Идентификатор заказа в ПЦ. Пример: `5587788`
`status`	`str`	✔	Статус заказа. Пример: `REGISTERED`
`inprogress`	`int`		Признак «выполняется ли ещё заказ» (0/1). Пример: `0`
`created_at`	`datetime`	✔	Дата и время регистрации заказа (`YYYY.MM.DD HH:MM:SS`). Пример: `2024.01.28 00:23:19`
`amount`	`int`	✔	Сумма заказа в минимальных единицах валюты (для RUB — копейки). Пример: `111`
`currency`	`int`	✔	Код валюты (ISO 4217). Пример: `643`
`email`	`str`		Email плательщика. Пример: `mail@somesite.com`
`phone`	`str`		Телефон плательщика. Пример: `79219999999`
`client_id`	`str`	✔	Внутренний идентификатор заказа на стороне ТСП. Пример: `12345ABC`
`description`	`str`	✔	Описание платежа. Пример: `notebook`
`return_url`	`str`	✔	URL возврата плательщика. Пример: `http://www.somesite.com/Accept.jsp`
`transactions`	`OperationsResponseDTO`	✔	Список операций по заказу (см. ниже).
`signature`	`str`		Цифровая подпись ответа ПЦ. Пример: `8f2a1c9e3b7d4056a1f8c2e9d3b6a70158fce29b4d7a1e6c0938fa2d17bc45e9`

Вложенный объект `transactions` (OperationsResponseDTO)

Поле	Тип	Обяз.	Описание
`number`	`int`	✔	Количество операций. (искл. из подписи)
`operations`	`list[OperationShortResponseDTO]`	✔	Список операций (см. ниже).

Вложенный объект `operations` (OperationShortResponseDTO)

Поле	Тип	Обяз.	Описание
`tx_id`	`int`	✔	Идентификатор операции в ПЦ. Пример: `2685`
`tx_created_at`	`datetime`	✔	Дата и время совершения операции в ПЦ (`YYYY-MM-DD HH:MM:SS`). Пример: `2012-09-06 10:19:54`
`tx_type`	`str`	✔	Тип операции. Пример: `PURCHASE`
`tx_status`	`str`	✔	Статус операции. Пример: `TIMEOUT`
`tx_reason_code`	`int`	✔	Код ответа на операцию ПЦ. Пример: `14`
`message`	`str`	✔	Краткое описание кода ответа на операцию ПЦ. Пример: `Timeout operation`
`cardholder_name`	`str`	✔	Имя на банковской карте Плательщика. Пример: `Mr card holder`
`pan`	`str`	✔	Маскированный номер банковской карты Плательщика. Пример: `676531******0129`
`email`	`str`	✔	Электронная почта Плательщика. Пример: `mail@somesite.com`
`amount`	`int`	✔	Сумма операции в минимальных единицах валюты (для RUB — копейки). Пример: `12000`
`currency`	`int`	✔	Код валюты по ISO 4217 (643 — RUB, 978 — EUR, 840 — USD). Пример: `643`
`tx_approval_code`	`str`	✔	Код авторизации, полученный в Банке на данную операцию. Пример: `739258`

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

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

{
    "id": 5587788,
    "status": "REGISTERED",
    "inprogress": 0,
    "created_at": "2024.01.28 00:23:19",
    "amount": 111,
    "currency": 643,
    "email": "mail@somesite.com",
    "phone": "79219999999",
    "client_id": "12345ABC",
    "description": "notebook",
    "return_url": "http://www.somesite.com/Accept.jsp",
    "transactions": {
        "number": 1,
        "operations": [
            {
                "tx_id": 2685,
                "tx_created_at": "2012-09-06 10:19:54",
                "tx_type": "PURCHASE",
                "tx_status": "TIMEOUT",
                "tx_reason_code": 14,
                "message": "Timeout operation",
                "cardholder_name": "Mr card holder",
                "pan": "676531******0129",
                "email": "mail@somesite.com",
                "amount": 12000,
                "currency": 643,
                "tx_approval_code": "739258"
            }
        ]
    },
    "signature": "8f2a1c9e3b7d4056a1f8c2e9d3b6a70158fce29b4d7a1e6c0938fa2d17bc45e9"
}

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

Примечания

Метод GET принимает те же параметры через query-строку; метод POST принимает тело application/json — по составу полей запрос идентичен для обоих методов.
Ответ может содержать ряд необязательных параметров, которые важно учесть при составлении подписи.