api/register - Регистрация заказа

Описание

HTTP‑метод: POST
URL: /api/register
Форма взаимодействия: Сервер-сервер
Формат тела запроса: application/json
Назначение: регистрация заказа в ПЦ.

URL

URLPATH

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

/api/register

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

Поле	Тип	Обяз.	Описание
`terminal`	`str`	✔	Уникальный идентификатор учетной записи ТСП в ПЦ.
`amount`	`int`	✔	Сумма заказа в минимальных единицах валюты. Для рублей - копейки.
`currency`	`int`	✔	Код валюты по ISO4217 (643 для RUB; 978 для EUR; 840 для USD).
`client_id`	`str`	✔	Номер заказа на стороне ТСП в его Системе магазина.
`description`	`str`	✔	Описание платежа.
`signature`	`str`	✔	Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.
Необязательные параметры
`receiver`	`object`		Данные получателя денежных средств. Значимые поля (см. структуру payer/receiver): `wallet_public_id`, `acc_number`, `contract`, `email`, `phone`.
`fee`	`int`		Эквайринговая комиссия в минимальных единицах валюты. Для рублей – копейки. Взимается с Плательщика дополнительно к основной сумме Заказа.
`return_url`	`str`		Адрес страницы на стороне ТСП, на которую автоматически переводится Плательщик по завершении Операции. ПЦ также передает на return_url идентификаторы Заказа и Операции в виде GET-параметров. Заполните значение параметра полностью, с указанием префикса (http:// или https://)
`fail_url`	`str`		Адрес страницы на стороне ТСП, на которую автоматически переводится Плательщик в случае неуспешного окончания проведения Операции. Если fail_url не указан, ПЦ считает его равным значению return_url.
`ttl`	`str`		Время в секундах, в течение которого по заказу может быть совершена Операция.
`fiscal_data`	`object`		Фискальные данные (вложенный JSON-объект, см. ниже).
`payer`	`object`		Данные Плательщика. Значимые поля (см. структуру payer/receiver): `public_id`, `email`, `address`, `city`, `post_code`, `phone`, `country`, `region`, `first_name`, `last_name`, `middle_name`, `is_notify`.
`mobile_deep_url`	`str`		Ссылка для возврата в мобильное приложение ТСП (мерчанта) после оплаты.
`callback_url`	`str`		URL для получения уведомлений об операциях по регистрируемому заказу.
`lang`	`str`		Язык отображения Платёжных страниц. Двухсимвольный код: RU, EN. По умолчанию берется из настроек учетной записи ТСП.
`comment`	`str`		Комментарий к заказу.
`bank`	`str`		Наименование банка Плательщика.
`fio`	`str`		Фамилия Имя Отчество получателя денежных средств.
`payment_system`	`int`		Платёжная система. Возможные значения: 0 (по умолчанию) — не установлена; 1 — Visa; 2 — MasterCard; 8 — Maestro; 10 – MIR; 11 — СБП; 12 — Uzcard; 13 — JCB; 14 — оплата со счёта мобильного телефона; 16 — HUMO; 17 — CHUP. (по умолчанию `0`)
`receipt_type`	`int`		Номер шаблона уведомления, отправляемого на email Плательщику. По умолчанию используется первый (стандартный) шаблон.
`card_exp_month`	`int`		Месяц срока действия Карты Плательщика. Используется для упрощения ввода параметров Карты в режиме оплаты через IVR.
`card_exp_year`	`int`		Год срока действия Карты Плательщика. Используется для упрощения ввода параметров Карты в режиме оплаты через IVR.
`origin_tx_id`	`int`		ID Операции в ПЦ (Purchase, Authorize), на основании которой был получен токен карты.
`multi_payment_data`	`str`		Строка, содержащая JSON-объект с ключом `payments`, описывающий дополнительные (сплитованные) платежи. Для каждого платежа обязательны `payment_number`, `amount`, `fee`, `currency`, `description`; опционально `reference`, `fiscal_positions`, `fiscal_data` (вложенный объект, см. структуру `fiscal_data` выше).
`is_notify_sms`	`bool`		Отправка sms-уведомления (счета) со ссылкой на оплату. Возможные значения: false (по умолчанию), true. (по умолчанию `False`)
`remind_days_before`	`int`		Количество дней до списания Рекуррентного платежа для отправки напоминания на email. От 0 до 10. По умолчанию 0 (не уведомлять). (по умолчанию `0`)
`free_requisites`	`object`		Набор свободных реквизитов для платежа по свободным реквизитам (см. ниже).
`recurrent`	`object`		Параметры для настройки рекуррентных платежей в рамках заказа (см. ниже).

multi_payment_data: значение этого поля — обычная строка (str), содержащая вложенный сериализованный JSON; она не разворачивается в объект на уровне тела запроса, а парсится и валидируется сервером внутри значения строки. При некорректном содержимом сервер возвращает ошибку валидации по полю multi_payment_data.

fiscal_data: полноценный вложенный JSON-объект — см. структуру ниже.

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

Поле	Тип	Обяз.	Описание
`group`	`str`		Группа устройств, с помощью которых будет пробит чек. По умолчанию `Main`.
`items`	`list[object]`	✔	Список позиций заказа (см. ниже).
`client`	`object`		Данные покупателя для чека: `email`, `phone`.
`company`	`object`		Данные оператора перевода для чека: `email`, `sno`, `payment_address`, `inn`.

Элемент `items[]`

Поле	Тип	Обяз.	Описание
`name`	`str`	✔	Название товара.
`price`	`int`		Цена за единицу предмета расчета с учетом скидок и наценок.
`quantity`	`int`		Количество/вес.
`sum`	`int`		Сумма в копейках. Вычисляется автоматически как `price * quantity`, переданное значение игнорируется.
`measurement_unit`	`str`		Единица измерения предмета расчета.
`payment_method`	`str`		Признак способа расчета. По умолчанию `full_payment`.
`payment_object`	`str`		Признак предмета расчета. По умолчанию `commodity`.
`vat_type`	`str`		Ставка НДС. По умолчанию `none`.

Пример:

{
    "group": "Main",
    "items": [
        {
            "name": "Название товара",
            "price": 10025,
            "quantity": 2,
            "sum": 20050,
            "measurement_unit": "кг",
            "payment_method": "full_payment",
            "payment_object": "commodity",
            "vat_type": "vat20"
        }
    ],
    "client": {
        "email": "client_email@mail.ru",
        "phone": "+71231234567"
    },
    "company": {
        "email": "company_email@mail.ru",
        "sno": "osn",
        "payment_address": "https://kvell.com",
        "inn": "1234567890"
    }
}

Вложенный объект `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`	Назначение платежа. Возможные значения: 1 — зарплата и т.п. (удержание не более 50%); 2 — периодические выплаты, алименты (без удержаний); 3 — компенсация вреда здоровью; 4 — разовые выплаты (без удержаний); 5 — разовый доход.
`P021`	`str`	Очередность платежа. Возможные значения 1–5 (см. правила очерёдности списания денежных средств).
`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`	Тип документа.

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

Поле	Тип	Описание
`period`	`int`	Код периода для Рекуррентных платежей.
`retry_period`	`int`	Интервал в днях для повтора неуспешного Рекуррентного платежа. По умолчанию 1.
`retry_count`	`int`	Допустимое количество неуспешных попыток списания Рекуррентного платежа. По умолчанию 3 (если `period` отличен от 0).
`is_retry`	`bool`	Поведение после исчерпания `retry_count`: `false` (по умолчанию) — остановить все последующие списания; `true` — пропустить текущий платёж и продолжить по графику. (по умолчанию `False`)
`start_date`	`str`	Дата начала периода действия Рекуррентного платежа (`yyyy.MM.dd HH:mm:ss`).
`end_date`	`str`	Дата окончания периода действия Рекуррентного платежа (`yyyy.MM.dd HH:mm:ss`).

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

Ответ всегда возвращается в формате JSON:

Поле	Тип	Обяз.	Описание
`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`
`parameters`	`ParametersResponseDTO`	✔	Массив дополнительных параметров заказа (см. ниже). На данный момент всегда пустой.
`signature`	`str`		Цифровая подпись ответа ПЦ. Пример: `8f2a1c9e3b7d4056a1f8c2e9d3b6a70158fce29b4d7a1e6c0938fa2d17bc45e9`

Вложенный объект `parameters` (ParametersResponseDTO)

Поле	Тип	Обяз.	Описание
`number`	`int`	✔	Количество параметров. Всегда `0`. (искл. из подписи)
`parameters`	`list[ParameterResponseDTO]`	✔	Список параметров. Всегда пустой массив `[]`.

Вложенный объект `parameters[]` (ParameterResponseDTO)

Поле	Тип	Обяз.	Описание
`name`	`str`	✔	Имя параметра.
`value`	`str`	✔	Значение параметра.

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

Успех (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",
    "parameters": {
        "number": 0,
        "parameters": []
    },
    "signature": "8f2a1c9e3b7d4056a1f8c2e9d3b6a70158fce29b4d7a1e6c0938fa2d17bc45e9"
}

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

Примечания

receiver.wallet_public_id заполняется, только если Заказ создаётся в рамках сервисов Кошелька (см. раздел «Кошелёк»); в остальных случаях поле не используется.
Ответ может содержать ряд необязательных параметров, которые важно учесть при составлении подписи.

api/register - Регистрация заказа

Описание

URL

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

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

Элемент items[]

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

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

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

Вложенный объект parameters (ParametersResponseDTO)

Вложенный объект parameters[] (ParameterResponseDTO)

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

Примечания

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

Элемент `items[]`

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

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

Вложенный объект `parameters` (ParametersResponseDTO)

Вложенный объект `parameters[]` (ParameterResponseDTO)