Общая информация о работе с ордерами#

Введение#

Ордер (order) - сущность, обозначающая заявку от мерчанта на обмен фиат <-> USDT.

Направления ордеров:

PayIn - фиат -> USDT
PayOut - USDT -> фиат

Типы ордеров:

P2P - перевод по номеру карты/счёта/аккаунта/телефона
QuasiEcom - оплата картой с подтверждением кодом 3-D Secure/SMS
Ecom - классическая оплата картой через интернет-эквайринг

Флоу ордеров:

H2H - интеграция по backend HTTP API: процессинг ведёт сервис по данным из запроса
PaymentPage - клиент мерчанта оплачивает на платёжной странице сервиса; мерчант получает URL страницы

Тип ордера QuasiEcom - PayIn-ордер с оплатой картой; его direction - всегда PayIn.

API для работы с ордерами#

Методы создания ордеров для каждого типа описаны на отдельных страницах:

Получение информации об ордерах - на странице "Получение информации об ордерах".

Для уведомлений мерчанта о финальных статусах ордера предусмотрен механизм коллбэков. См. страницу "Коллбэки".

Статусная модель#

PayIn - P2P#

Статус	Описание
`created`	Ордер зарегистрирован в системе
`rejected`	Ордер отклонён
`declined_by_gateway`	Не удалось подобрать провайдера для обработки ордера
`payment_pending`	Ордер обработан. Ожидание платежа от клиента
`expired`	Истек TTL ордера, платеж не был произведен
`succeeded`	Ордер успешно исполнен, платеж был произведен
`succeeded_by_appeal`	Ордер признан успешным по апелляции
`failed_by_appeal`	Ордер признан зафейленным по апелляции

Значение TTL по умолчанию - 15 минут.

PayIn - QuasiEcom#

Статус	Описание
`created`	Ордер зарегистрирован в системе
`rejected`	Ордер отклонён
`declined_by_gateway`	Не удалось подобрать провайдера для обработки ордера
`confirm_waiting`	Ожидание кода подтверждения
`waiting_for_terminal`	Ожидание обработки платежа провайдером
`failed_by_terminal`	Провадер не смог произвести платеж
`expired`	Истек TTL ордера, платеж не был произведен
`succeeded`	Ордер успешно исполнен, платеж был произведен
`succeeded_by_appeal`	Ордер признан успешным по апелляции
`failed_by_appeal`	Ордер признан зафейленным по апелляции

PayIn - Ecom#

Статус	Описание
`created`	Ордер зарегистрирован в системе
`rejected`	Ордер отклонён
`declined_by_gateway`	Не удалось подобрать провайдера для обработки ордера
`submit_in_progress`	Внутренний: отправка карты на шлюз, короткоживущий
`confirm_waiting`	Платёж создан на шлюзе, ожидание результата (у клиента - 3-D Secure на стороне шлюза)
`failed_by_terminal`	Провайдер не смог произвести платеж
`expired`	Истек TTL ордера, платеж не был произведен
`succeeded`	Ордер успешно исполнен, платеж был произведен
`succeeded_by_appeal`	Ордер признан успешным по апелляции
`failed_by_appeal`	Ордер признан зафейленным по апелляции

Значение TTL задаётся настройками метода.

PayOut - P2P#

Статус	Описание
`created`	Ордер зарегистрирован в системе
`rejected`	Ордер отклонён
`terminal_selecting`	Подбор провайдера для платежа
`payment_in_progress`	Провайдер выбран. Ожидание платежа от провайдера
`expired`	Истек TTL ордера, платеж не был произведен
`terminal_failed`	Провайдер не смог произвести платеж
`expired_without_callback`	Истек TTL ордера, но отсутствует информация об успешности платежа от провайдера
`succeeded`	Ордер успешно исполнен, платеж был произведен
`succeeded_by_appeal`	Ордер помечен успешным по апелляции
`failed_by_appeal`	Платеж не был осуществлен, установлено по апелляции
`all_terminals_failed`	Не удалось подобрать провайдера для платежа. Платеж не был осуществлен

Значение TTL обсуждается при интеграции.

Модель ордера#

Единая модель OrderOut используется в карточке ордера, списке и вебхуке:

Поле	Тип	Обязательное	Описание
`id`	string	да	UUID ордера
`createdAt`	string	да	Дата и время создания, RFC 3339
`updatedAt`	string	да	Дата и время обновления, RFC 3339
`type`	string	да	Тип: `PayIn`, `PayOut`, `QuasiEcom`, `Ecom`
`direction`	string	да	Направление: `PayIn` или `PayOut`
`status`	string	да	Статус, см. статусную модель
`merchantOrderID`	string	нет	Идентификатор ордера мерчанта
`clientID`	string	нет	Идентификатор клиента
`methodID`	integer	да	Метод ордера
`paymentDetails`	object	нет	Реквизиты платежа, см. "Реквизиты платежа"
`currencyCode`	string	да	ISO 4217 валюты ордера
`amount`	float64	да	Сумма в фиате
`merchantCommission`	float64	нет*	Комиссия мерчанта в валюте ордера
`amountUSDT`	float64	нет*	Сумма ордера в USDT
`merchantCommissionUSDT`	float64	нет*	Комиссия мерчанта в USDT
`exchangeRate`	float64	нет*	Курс фиат - USDT
`trafficType`	string	да	Тип трафика

* - amountUSDT, merchantCommission и merchantCommissionUSDT присутствуют после расчёта по ордеру; при создании ордера payment-page (статус created) отсутствуют.

* - exchangeRate фиксируется курсом метода при создании и присутствует сразу; в схеме OpenAPI опционален.

Реквизиты платежа#

Реквизиты платежа - куда клиенту платить - возвращаются блоком paymentDetails в ответе создания PayIn P2P H2H и в теле коллбэка (для P2P). Поля блока:

Поле	Тип	Обязательное	Описание
`requisiteTypeCode`	string	да	Код типа реквизита
`recipientName`	string	нет	Имя держателя реквизита
`recipientNumber`	string	нет	Значение реквизита для перевода
`recipientBank`	string	нет	Банк реквизита

При оплате по ссылке значение передаётся в recipientNumber. methodID - поле самого ордера, в блок не входит. Для QuasiEcom и Ecom блок не отдаётся - оплата выполняется картой клиента.

Данные клиента#

Объект clientMetadata в запросах создания ордеров (все поля необязательные; отдельные методы требуют конкретные поля - уточняйте при интеграции):

Поле	Тип	Описание
`phone`	string	Телефон
`operator`	string	Оператор
`name`	string	Имя
`email`	string	Email
`otp`	string	Одноразовый код оператора
`documentType`	string	Тип документа, удостоверяющего личность
`documentNumber`	string	Номер документа, удостоверяющего личность
`streetAddress`	string	Адрес
`city`	string	Город
`zipCode`	string	Почтовый индекс клиента

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

Тело успешного ответа - плоский JSON без конверта result/data. Список возвращается в виде { items, total }, где total - количество сущностей по фильтрам без учёта пагинации. Идентификатор запроса возвращается в заголовке X-Request-Id.

Формат ошибок, HTTP-коды и таблица errorCode - на странице "Авторизация запросов".

Форматы данных в API#

Время: string, RFC 3339, например 2026-08-31T06:37:45.776331Z
Суммы в фиате: float64, 2 знака после запятой (округление на входе)
Суммы в USDT: float64 с точностью до 6 знаков после запятой