api/recurring - Повторное (Автоматическое) списание по карте

HTTP‑метод: POST
URL: /api/recurring
Форма взаимодействия: Сервер-сервер
Формат тела запроса: application/json
Назначение: выполнение рекуррентной (автоматической) операции RECURRING по ранее зарегистрированному заказу.
Дополнительно: метод подразумевает ведение графика Рекуррентных платежей на стороне ТСП. Новые платежи создаются как операции в рамках одного и того же заказа.

URL

URLPATH

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

/api/recurring

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

Поле	Тип	Обяз.	Описание
`terminal`	`str`	✔	Уникальный идентификатор учетной записи ТСП в ПЦ.
`order_id`	`int`	✔	Уникальный идентификатор Заказа в ПЦ, полученный по результатам Запроса api/register.
`amount`	`int`	✔	Сумма заказа в минимальных единицах валюты. Для рублей - копейки.
`currency`	`int`	✔	Код валюты по ISO4217 (643 для RUB; 978 для EUR; 840 для USD).
`signature`	`str`	✔	Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.
Необязательные параметры
`fee`	`int`		Эквайринговая комиссия в минимальных единицах валюты. Для рублей – копейки. Взимается с Плательщика дополнительно к основной сумме Заказа.

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

Важно: в отличие от остальных методов api/*, ответ api/recurring в текущей реализации не проходит через типизированную response-модель — эндпоинт возвращает объект dict, обёрнутый в ключ operation, с именами полей (order_state, reference, date, type, state, reason_code, name, pan, approval_code), отличными от стиля именования, который используют остальные страницы этой документации (order_status, client_id, tx_... и т.д.). Значения полей amount и currency в этом ответе — строки, а не числа.

Поле (внутри `operation`)	Тип	Описание
`order_id`	`int`	Идентификатор заказа в ПЦ.
`order_state`	`str`	Статус заказа.
`reference`	`str`	Номер заказа на стороне ТСП.
`id`	`int`	Идентификатор операции в ПЦ.
`date`	`str`	Дата и время совершения операции в ПЦ (`YYYY.MM.DD HH:MM:SS`).
`type`	`str`	Тип операции.
`state`	`str`	Статус операции.
`reason_code`	`str`	Код ответа на операцию ПЦ.
`message`	`str`	Краткое описание кода ответа на операцию ПЦ.
`name`	`str`	Имя на банковской карте Плательщика.
`pan`	`str`	Маскированный номер банковской карты Плательщика.
`email`	`str`	Электронная почта Плательщика.
`amount`	`str`	Сумма заказа в минимальных единицах валюты (для RUB — копейки), в виде строки.
`currency`	`str`	Код валюты по ISO 4217 (643 — RUB, 978 — EUR, 840 — USD), в виде строки.
`approval_code`	`str`	Код авторизации, полученный в Банке на данную операцию.
`signature`	`str`	Цифровая подпись сообщения.

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

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

{
    "operation": {
        "order_id": 441,
        "order_state": "AUTHORIZED",
        "reference": "12345ABC",
        "id": 10427,
        "date": "2013.02.28 00:23:19",
        "type": "AUTHORIZE",
        "state": "APPROVED",
        "reason_code": "1",
        "message": "Successful financial transaction",
        "name": "cardholder name",
        "pan": "676531******0129",
        "email": "mail@somesite.com",
        "amount": "111",
        "currency": "643",
        "approval_code": "739258",
        "signature": "3c7e0a91f6d284b5c1e9a03d7f28b46019e5c8a2f0d3b7461c8ea9f52d06b31"
    }
}

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

Примечания

На момент написания документации обработчик api/recurring всегда возвращает один и тот же фиксированный (демонстрационный) объект operation, показанный выше, независимо от переданных данных в теле запроса — реальная бизнес-логика проведения рекуррентного платежа не выполняется. Это текущее поведение сервиса, а не ошибка документации.
Ответ может содержать ряд необязательных параметров, которые важно учесть при составлении подписи.
Для лучшего разделения и структуры рекомендуется использовать операции по токенам (api/purchase-by-token), а не рекуррентные в рамках заказа.