memo), мониторит
сеть на входящую транзакцию и сообщает об оплате двумя способами: через статусы (которые
вы читаете GET-запросами) и через webhooks, которые платформа сама
шлёт на ваш callback_url.
Все запросы подписываются HMAC — см. Аутентификация. Ответы приходят
в едином конверте: { "ok": true, "data": ... } при успехе и
{ "ok": false, "error": { "code": "...", "message": "..." } } при ошибке (см.
Ошибки). Все суммы — строки, чтобы не терять точность на float.
Во всех примерах ниже базовый URL и идентификатор ключа одни и те же:
https://wallet.your-exchange.com и X-Api-Id: pk_live_a1b2c3d4. Подставьте свои
значения из админ-кабинета.Эндпоинты
Адрес или адрес + memo: TON против TRON/EVM
Платформа поддерживает две модели идентификации входящего платежа. От модели зависит, что именно нужно показать вашему клиенту для оплаты.Address-based (TRON, EVM)
На каждый депозит выдаётся уникальный адрес. В ответе
memo равен null. Клиент
переводит средства на data.address — этого достаточно, чтобы платёж был привязан к
нужной заявке.Memo-based (TON)
Используется общий приёмный адрес плюс уникальный
memo (он же comment/tag).
В ответе memo не равен null. Клиент обязан указать и data.address, и data.memo —
без memo платёж невозможно сопоставить с заявкой.Создать депозит
POST /v1/public/deposits
Создаёт новый депозит и возвращает реквизиты для оплаты. Вызывайте этот эндпоинт в момент,
когда клиент на стороне обменника выбрал валюту и готов платить.
Операция идемпотентна по комбинации (site, order_id, asset) и, опционально, по заголовку
X-Idempotency-Key. Подробнее — в разделе Идемпотентность.
Создание новых депозитов требует активной лицензии инстанса. Если лицензия не активирована,
эндпоинт вернёт
403 LICENSE_REQUIRED. Уже идущие депозиты при этом не затрагиваются.Тело запроса
string
required
Код актива, например
USDT_TRC20, TRX, USDT_TON. Полный список доступных активов —
GET /v1/public/assets. Максимум 64 символа.string
Ваш идентификатор заявки (label), 1–255 символов. Опционально — если не передать,
платформа сгенерирует уникальный код вида
NNNN-NNNN-NNNN. По умолчанию (строгий режим)
order_id должен быть уникален в рамках сайта: повтор уже использованного значения
вернёт 409 DUPLICATE_ORDER_ID. Один и тот же order_id на другой валюте также вернёт
409. Для безопасных ретраев используйте X-Idempotency-Key — он проверяется раньше,
чем срабатывает эта ошибка. См. Идемпотентность.string
Ожидаемая сумма как decimal-строка, например
"100.50". Опционально — если не
передать, берётся минимальная сумма приёма актива (asset.minDepositAmount). Значение
"0" означает «принять любую сумму». Число знаков после запятой не должно превышать
точность актива, иначе вернётся 400 AMOUNT_TOO_MANY_DECIMALS.string
Опциональная заметка к депозиту (видна только вам в админ-кабинете). Максимум 1024 символа.
memo:
Покажите клиенту
data.address, а если data.memo не равен null (memo-сети) — ещё и
data.memo как обязательное поле. transaction равен null до тех пор, пока в сети не
будет замечена входящая транзакция.Поля ответа
Ответ создания и все GET-эндпоинты (кроме AML) возвращают один и тот же объект депозита:string
Публичный идентификатор депозита. Используйте его в
GET /v1/public/deposits/{uuid}.string
Ваш
order_id (label). Если вы его не передавали, здесь будет авто-сгенерированный код.string
Адрес для оплаты. Для memo-сетей — общий приёмный адрес (используется вместе с
memo).string | null
Memo/comment. Не равен
null и обязателен для memo-сетей (TON); null для address-based
сетей (TRON, EVM).string
Код актива депозита.
string
Ожидаемая сумма (строка).
"0" означает, что принимается любая сумма.string
Бизнес-статус депозита. Полный набор и переходы — Статусы депозита.
string
ISO-8601. До какого момента сеть мониторится на оплату. После этого момента неоплаченный
депозит уходит в
expired.string | null
Ссылка на адрес в блок-эксплорере (
null, если для актива не настроен шаблон).object | null
On-chain данные входящей транзакции.
null, пока депозит не получил ни одной транзакции.Получить депозит
GET /v1/public/deposits/{uuid} — по uuid из ответа на создание.
GET /v1/public/deposits/by-order-id/{orderId} — по вашему order_id.
Оба эндпоинта возвращают один и тот же объект депозита. Поле transaction заполняется, как
только в сети замечена входящая tx, и обновляется с каждым новым подтверждением. Опрашивайте
эндпоинт периодически либо опирайтесь на webhooks, чтобы не дёргать
API лишний раз.
Это GET-запросы без тела, поэтому подписываемое сообщение —
X-Timestamp + "." + "", то есть просто "1769990500." (timestamp и точка).
См. Аутентификация.Список депозитов
GET /v1/public/deposits?page=1&perPage=20&status=paid
Возвращает историю депозитов вашего сайта в обратном хронологическом порядке. Каждый элемент
имеет ту же форму, что и одиночный депозит.
Параметры запроса
integer
default:"1"
Номер страницы, начиная с 1.
integer
default:"20"
Размер страницы. Минимум 1, максимум 100.
string
Фильтр по статусу: одно значение (
?status=paid) или несколько через запятую
(?status=paid,paid_over). Допустимые значения — из набора бизнес-статусов депозита
(см. Статусы депозита). Неизвестные значения молча игнорируются.Поля meta
number
Текущая страница.
number
Размер страницы.
number
Всего записей по всем страницам (для пагинации).
AML-данные депозита
GET /v1/public/deposits/{uuid}/aml
GET /v1/public/deposits/by-order-id/{orderId}/aml
Отдельный под-ресурс с результатом AML-скрининга source-of-funds — адреса отправителя
входящей транзакции. Основной объект депозита намеренно не содержит AML-полей; запрашивайте
их явно через эти эндпоинты.
amlStatus равен not_checked, если AML-скрининг выключен в настройках инстанса, либо
транзакция ещё не замечена, либо сеть не поддерживается AML-провайдером. Значение
checkState: "skipped" НЕ означает «чисто» — это означает, что проверка не выполнялась.Поля AML-ответа
string
UUID депозита (тот же, что в
GET /{uuid}).string
Ваш
order_id (label).string
Код актива депозита.
string
Код сети депозита (например
TRON, TON).string | null
Адрес отправителя входящей транзакции — именно он проходит AML-скрин.
null, пока tx не
замечена.string
Итоговый AML-статус депозита:
not_checked (не проверялся / AML выключен) | passed (чисто)
| flagged (подозрительно, но не блокировка) | hold (заблокирован, ждёт ручного решения)
| rejected (отклонён).string | null
Состояние запроса к провайдеру:
pending | success | failed | error | skipped.
null, если проверки не было.string | null
Risk-score 0–100 (строка).
null, если проверки не было.string | null
Уровень риска:
low | medium | high | severe. Значение severe соответствует
санкциям, терроризму, краденым средствам или эксплуатации — блокировка независимо от score.string | null
Решение скрининга:
pass | flag | block.string | null
Код AML-провайдера.
string | null
Топ-сигнал риска (категория с максимальным весом), например
mixer, sanctions, scam,
darknet.object | null
Карта сигналов риска и их весов (0..1).
null, если провайдер их не вернул.string | null
Ссылка на полный отчёт провайдера (если есть).
Публичная share-ссылка на отчёт (если есть).
string | null
ISO-8601. Когда выполнен AML-скрин.
null, если проверки не было.string | null
Ручное действие оператора над заблокированным депозитом:
release (разрешить свип) |
quarantine_now.string | null
ISO-8601. Когда применено ручное действие.
string | null
Причина ручного действия (комментарий оператора).
Частые ошибки
Полный список кодов и формат конверта ошибки — на странице Ошибки.
Частые вопросы
Когда поле transaction перестаёт быть null?
Когда поле transaction перестаёт быть null?
Как только платформа замечает первую входящую транзакцию на адрес (и memo) депозита.
До этого момента
transaction равен null, а status остаётся check. После детекции
статус переходит в process, а поля транзакции обновляются с каждым подтверждением.Как отличить точную оплату от переплаты или недоплаты?
Как отличить точную оплату от переплаты или недоплаты?
По финальному статусу:
paid — оплачено ровно ожидаемой суммой, paid_over — больше,
wrong_amount — меньше. Если expectedAmount равен "0", принимается любая сумма и
исход всегда paid. Точную фактическую сумму смотрите в transaction.receivedAmount.
Подробнее — в Статусах депозита.Нужно ли опрашивать API или можно полагаться на webhooks?
Нужно ли опрашивать API или можно полагаться на webhooks?
Рекомендуем основным каналом сделать webhooks — платформа сама
уведомит о смене статуса. GET-эндпоинты используйте как резервный механизм (для
реконсиляции и при пропущенных вебхуках), опрашивая их с разумным интервалом.
Что вернётся, если повторить создание с тем же order_id?
Что вернётся, если повторить создание с тем же order_id?
В строгом режиме (по умолчанию) —
409 DUPLICATE_ORDER_ID, второй депозит не создаётся.
Чтобы безопасно повторять запрос при сетевых сбоях, передавайте X-Idempotency-Key: при
совпадении ключа и тела вернётся ранее созданный депозит. См. Идемпотентность.Можно ли получить чужой депозит по uuid?
Можно ли получить чужой депозит по uuid?
Нет. Все запросы скоупятся по вашему сайту. Запрос депозита, принадлежащего другому сайту,
вернёт
404 DEPOSIT_NOT_FOUND — платформа не раскрывает существование чужих UUID.