Глоссарий и соглашения по полям
Заголовки запроса
| Заголовок | Обязателен | Определение |
|---|
| x-api-key | Да | API-ключ, выпущенный в приложении (раздел «Бизнес»). Организация определяется по хосту запроса |
| Content-Type | Да (POST) | application/json для запросов создания |
Суммы и валюта
| Термин | Определение |
|---|
| amount | Строка целого числа в минорных единицах |
| amount_with_fee | Сумма с включенной комиссией (минорные единицы) |
| currency | Код валюты / токена (USDT) |
| currency_dest | Валюта зачисления для конвертации (FX). Опционально; по умолчанию равна currency |
Идентификаторы
| Термин | Определение |
|---|
| id | Внутренний UUID транзакции |
| txid | Идемпотентный внешний идентификатор клиента. При передаче обязан быть валидным UUID; может быть опущен |
Маршрутизация и среда
| Термин | Определение |
|---|
| route | Алиас маршрута обработки, настроенный для API-ключа |
| env | Среда: prod (по умолчанию) или test |
Статусы
| Статус | Значение |
|---|
| created | Принята, ожидает обработки |
| new | Начальное состояние до старта обработки |
| authorizing | Идёт авторизация |
| pre_authorized_3ds | Ожидает 3DS-аутентификацию |
| action_required | Требуется доп. действие (3DS / доп. авторизация) |
| charging | В процессе проведения |
| payment_suspended | Входящая транзакция временно приостановлена |
| payout_suspended | Исходящая транзакция временно приостановлена |
| charged | Успешно завершена (терминальный) |
| reversed | Списание отменено (терминальный) |
| refunded | Возврат (терминальный) |
| rejected | Отказ (терминальный) |
| failed | Сбой (терминальный) |
Терминальные статус ы: charged, reversed, refunded, rejected, failed. Типичный happy-path: created → charging → charged.
Временные поля
| Поле | Значение |
|---|
| started | Время начала обработки (ISO) |
| finished | Время достижения терминального статуса |
Объекты money_storage
| Поле | Значение |
|---|
| network | Blockchain-сеть (ETH, TRX и т.п.) |
| type | Тип инструмента (bank_card, p2p_proxy) |
| wallet_id | Идентификатор кошелька |
| cardnumber | PAN виртуальной карты |
| cvv | CVV виртуальной карты |
| exp_month / exp_year | Срок действия (строки) |
| cardholder | Имя держателя |
Ошибки
| Поле | Значение |
|---|
| error_description | Текстовое описание ошибки (нестабильно) |
Идемпотентность
Используйте уникальный txid (валидный UUID) на каждую бизнес-операцию. Повторяйте запрос создания только с тем же txid — повтор вернёт уже созданную транзакцию, а не создаст новую. Не-UUID txid отклоняется с 422 invalid_txid.
Поллинг
Интервалы: 1s → 2s → 4s → 8s (лимит, например 30s) до charged / rejected.
Webhook
Информирует об изменении — статус подтверждайте через GET.