Депозиты — приём платежей

Депозит — это запрос на приём средств от вашего клиента. Платформа создаёт уникальную цель приёма (адрес, а для memo-сетей — общий адрес плюс уникальный 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. Подставьте свои значения из админ-кабинета.

Эндпоинты

Метод	Путь	Назначение
`POST`	`/v1/public/deposits`	создать депозит
`GET`	`/v1/public/deposits`	список (история), с пагинацией и фильтром по статусу
`GET`	`/v1/public/deposits/{uuid}`	получить депозит по его `uuid`
`GET`	`/v1/public/deposits/by-order-id/{orderId}`	получить депозит по вашему `order_id`
`GET`	`/v1/public/deposits/{uuid}/aml`	AML-данные (source-of-funds) по `uuid`
`GET`	`/v1/public/deposits/by-order-id/{orderId}/aml`	AML-данные по вашему `order_id`

Адрес или адрес + 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 платёж невозможно сопоставить с заявкой.

Для memo-сетей (TON) memo обязателен. Если клиент отправит средства на общий адрес без memo или с неверным memo, платёж не будет автоматически привязан к депозиту. Всегда проверяйте data.memo !== null и показывайте memo как отдельное обязательное поле.

Создать депозит

POST /v1/public/deposits Создаёт новый депозит и возвращает реквизиты для оплаты. Вызывайте этот эндпоинт в момент, когда клиент на стороне обменника выбрал валюту и готов платить. Операция идемпотентна по комбинации (site, order_id, asset) и, опционально, по заголовку X-Idempotency-Key. Подробнее — в разделе Идемпотентность.

Создание новых депозитов требует активной лицензии инстанса. Если лицензия не активирована, эндпоинт вернёт 403 LICENSE_REQUIRED. Уже идущие депозиты при этом не затрагиваются.

Тело запроса

assetCode

string

required

Код актива, например USDT_TRC20, TRX, USDT_TON. Полный список доступных активов — GET /v1/public/assets. Максимум 64 символа.

orderId

string

Ваш идентификатор заявки (label), 1–255 символов. Опционально — если не передать, платформа сгенерирует уникальный код вида NNNN-NNNN-NNNN. По умолчанию (строгий режим) order_id должен быть уникален в рамках сайта: повтор уже использованного значения вернёт 409 DUPLICATE_ORDER_ID. Один и тот же order_id на другой валюте также вернёт 409. Для безопасных ретраев используйте X-Idempotency-Key — он проверяется раньше, чем срабатывает эта ошибка. См. Идемпотентность.

expectedAmount

string

Ожидаемая сумма как decimal-строка, например "100.50". Опционально — если не передать, берётся минимальная сумма приёма актива (asset.minDepositAmount). Значение "0" означает «принять любую сумму». Число знаков после запятой не должно превышать точность актива, иначе вернётся 400 AMOUNT_TOO_MANY_DECIMALS.

comment

string

Опциональная заметка к депозиту (видна только вам в админ-кабинете). Максимум 1024 символа.

curl -X POST https://wallet.your-exchange.com/v1/public/deposits \
  -H "X-Api-Id: pk_live_a1b2c3d4" \
  -H "X-Timestamp: 1769990400" \
  -H "X-Signature: 9b1f...c0e2" \
  -H "Content-Type: application/json" \
  -d '{
    "assetCode": "USDT_TRC20",
    "orderId": "WX-1042",
    "expectedAmount": "100.50"
  }'

{
  "ok": true,
  "data": {
    "uuid": "8f3a1c2e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
    "orderId": "WX-1042",
    "address": "TKh9aBcDeFgHiJkLmNoPqRsTuVwXyZ12c4",
    "memo": null,
    "assetCode": "USDT_TRC20",
    "expectedAmount": "100.50",
    "status": "check",
    "expiresAt": "2026-06-26T21:30:00.000Z",
    "explorerAddressUrl": "https://tronscan.org/#/address/TKh9aBcDeFgHiJkLmNoPqRsTuVwXyZ12c4",
    "transaction": null
  }
}

Пример ответа для memo-сети (TON) — обратите внимание на непустой memo:

{
  "ok": true,
  "data": {
    "uuid": "2b7d9e44-1a3c-4f88-bc05-6d2e9f0a1b34",
    "orderId": "WX-1043",
    "address": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
    "memo": "WP-1A2B3C4D",
    "assetCode": "USDT_TON",
    "expectedAmount": "50",
    "status": "check",
    "expiresAt": "2026-06-26T21:35:00.000Z",
    "explorerAddressUrl": "https://tonviewer.com/EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
    "transaction": null
  }
}

Покажите клиенту data.address, а если data.memo не равен null (memo-сети) — ещё и data.memo как обязательное поле. transaction равен null до тех пор, пока в сети не будет замечена входящая транзакция.

Поля ответа

Ответ создания и все GET-эндпоинты (кроме AML) возвращают один и тот же объект депозита:

uuid

string

Публичный идентификатор депозита. Используйте его в GET /v1/public/deposits/{uuid}.

orderId

string

Ваш order_id (label). Если вы его не передавали, здесь будет авто-сгенерированный код.

address

string

Адрес для оплаты. Для memo-сетей — общий приёмный адрес (используется вместе с memo).

memo

string | null

Memo/comment. Не равен null и обязателен для memo-сетей (TON); null для address-based сетей (TRON, EVM).

assetCode

string

Код актива депозита.

expectedAmount

string

Ожидаемая сумма (строка). "0" означает, что принимается любая сумма.

status

string

Бизнес-статус депозита. Полный набор и переходы — Статусы депозита.

expiresAt

string

ISO-8601. До какого момента сеть мониторится на оплату. После этого момента неоплаченный депозит уходит в expired.

explorerAddressUrl

string | null

Ссылка на адрес в блок-эксплорере (null, если для актива не настроен шаблон).

transaction

object | null

On-chain данные входящей транзакции. null, пока депозит не получил ни одной транзакции.

Show поля transaction

networkStatus

string

Статус транзакции в сети: pending → mempool → confirmed | fail.

receivedAmount

string | null

Фактически полученная сумма (строка). null, пока tx не подтверждена.

txhash

string | null

Хеш входящей транзакции.

confirmations

number | null

Текущее число подтверждений сети.

requiredConfirmations

number | null

Сколько подтверждений требуется для финализации (asset.minConfirmations).

blockNumber

string | null

Номер блока (строка, т.к. может превышать Number.MAX_SAFE_INTEGER). null, пока tx в mempool.

explorerTxUrl

string | null

Ссылка на транзакцию в блок-эксплорере.

detectedAt

string | null

ISO-8601. Когда транзакция впервые замечена в сети.

paidAt

string | null

ISO-8601. Когда депозит финализирован (paid / paid_over / wrong_amount). null, пока не финализирован.

Получить депозит

GET /v1/public/deposits/{uuid} — по uuid из ответа на создание. GET /v1/public/deposits/by-order-id/{orderId} — по вашему order_id. Оба эндпоинта возвращают один и тот же объект депозита. Поле transaction заполняется, как только в сети замечена входящая tx, и обновляется с каждым новым подтверждением. Опрашивайте эндпоинт периодически либо опирайтесь на webhooks, чтобы не дёргать API лишний раз.

curl https://wallet.your-exchange.com/v1/public/deposits/8f3a1c2e-5b6d-4e7f-9a0b-1c2d3e4f5a6b \
  -H "X-Api-Id: pk_live_a1b2c3d4" \
  -H "X-Timestamp: 1769990500" \
  -H "X-Signature: 4d8e...91af"

Это GET-запросы без тела, поэтому подписываемое сообщение — X-Timestamp + "." + "", то есть просто "1769990500." (timestamp и точка). См. Аутентификация.

{
  "ok": true,
  "data": {
    "uuid": "8f3a1c2e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
    "orderId": "WX-1042",
    "address": "TKh9aBcDeFgHiJkLmNoPqRsTuVwXyZ12c4",
    "memo": null,
    "assetCode": "USDT_TRC20",
    "expectedAmount": "100.50",
    "status": "process",
    "expiresAt": "2026-06-26T21:30:00.000Z",
    "explorerAddressUrl": "https://tronscan.org/#/address/TKh9aBcDeFgHiJkLmNoPqRsTuVwXyZ12c4",
    "transaction": {
      "networkStatus": "mempool",
      "receivedAmount": "100.50",
      "txhash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
      "confirmations": 3,
      "requiredConfirmations": 19,
      "blockNumber": null,
      "explorerTxUrl": "https://tronscan.org/#/transaction/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
      "detectedAt": "2026-06-26T20:35:12.000Z",
      "paidAt": null
    }
  }
}

Прогресс подтверждений считается как transaction.confirmations / transaction.requiredConfirmations (например 3 / 19). Чтобы отличить точную оплату от переплаты или недоплаты, сравните transaction.receivedAmount с expectedAmount — подробности в Статусах депозита.

Список депозитов

GET /v1/public/deposits?page=1&perPage=20&status=paid Возвращает историю депозитов вашего сайта в обратном хронологическом порядке. Каждый элемент имеет ту же форму, что и одиночный депозит.

Параметры запроса

page

integer

default:"1"

Номер страницы, начиная с 1.

perPage

integer

default:"20"

Размер страницы. Минимум 1, максимум 100.

status

string

Фильтр по статусу: одно значение (?status=paid) или несколько через запятую (?status=paid,paid_over). Допустимые значения — из набора бизнес-статусов депозита (см. Статусы депозита). Неизвестные значения молча игнорируются.

{
  "ok": true,
  "data": {
    "items": [
      {
        "uuid": "8f3a1c2e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
        "orderId": "WX-1042",
        "address": "TKh9aBcDeFgHiJkLmNoPqRsTuVwXyZ12c4",
        "memo": null,
        "assetCode": "USDT_TRC20",
        "expectedAmount": "100.50",
        "status": "paid",
        "expiresAt": "2026-06-26T21:30:00.000Z",
        "explorerAddressUrl": "https://tronscan.org/#/address/TKh9aBcDeFgHiJkLmNoPqRsTuVwXyZ12c4",
        "transaction": {
          "networkStatus": "confirmed",
          "receivedAmount": "100.50",
          "txhash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
          "confirmations": 19,
          "requiredConfirmations": 19,
          "blockNumber": "65123456",
          "explorerTxUrl": "https://tronscan.org/#/transaction/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
          "detectedAt": "2026-06-26T20:35:12.000Z",
          "paidAt": "2026-06-26T20:41:05.000Z"
        }
      },
      {
        "uuid": "7c2b8d11-4e3a-49b0-8f21-0a1b2c3d4e5f",
        "orderId": "WX-1041",
        "address": "TQ5n...wY9k",
        "memo": null,
        "assetCode": "TRX",
        "expectedAmount": "0",
        "status": "check",
        "expiresAt": "2026-06-26T22:00:00.000Z",
        "explorerAddressUrl": "https://tronscan.org/#/address/TQ5n...wY9k",
        "transaction": null
      }
    ],
    "meta": { "page": 1, "perPage": 20, "total": 137 }
  }
}

Поля `meta`

page

number

Текущая страница.

perPage

number

Размер страницы.

total

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" НЕ означает «чисто» — это означает, что проверка не выполнялась.

curl https://wallet.your-exchange.com/v1/public/deposits/8f3a1c2e-5b6d-4e7f-9a0b-1c2d3e4f5a6b/aml \
  -H "X-Api-Id: pk_live_a1b2c3d4" \
  -H "X-Timestamp: 1769990600" \
  -H "X-Signature: 7a2c...44de"

{
  "ok": true,
  "data": {
    "uuid": "8f3a1c2e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
    "orderId": "WX-1042",
    "assetCode": "USDT_TRC20",
    "network": "TRON",
    "senderAddress": "TSenderAddrXyz1234567890abcdefGhJk",
    "amlStatus": "passed",
    "checkState": "success",
    "riskScore": "12.50",
    "riskLevel": "low",
    "decision": "pass",
    "provider": "getblock",
    "topSignal": "exchange",
    "signals": { "exchange": 0.7, "p2p": 0.2 },
    "reportUrl": null,
    "shareUrl": null,
    "checkedAt": "2026-06-26T20:36:00.000Z",
    "manualAction": null,
    "manualActionAt": null,
    "manualActionReason": null
  }
}

Поля AML-ответа

uuid

string

UUID депозита (тот же, что в GET /{uuid}).

orderId

string

Ваш order_id (label).

assetCode

string

Код актива депозита.

network

string

Код сети депозита (например TRON, TON).

senderAddress

string | null

Адрес отправителя входящей транзакции — именно он проходит AML-скрин. null, пока tx не замечена.

amlStatus

string

Итоговый AML-статус депозита: not_checked (не проверялся / AML выключен) | passed (чисто) | flagged (подозрительно, но не блокировка) | hold (заблокирован, ждёт ручного решения) | rejected (отклонён).

checkState

string | null

Состояние запроса к провайдеру: pending | success | failed | error | skipped. null, если проверки не было.

riskScore

string | null

Risk-score 0–100 (строка). null, если проверки не было.

riskLevel

string | null

Уровень риска: low | medium | high | severe. Значение severe соответствует санкциям, терроризму, краденым средствам или эксплуатации — блокировка независимо от score.

decision

string | null

Решение скрининга: pass | flag | block.

provider

string | null

Код AML-провайдера.

topSignal

string | null

Топ-сигнал риска (категория с максимальным весом), например mixer, sanctions, scam, darknet.

signals

object | null

Карта сигналов риска и их весов (0..1). null, если провайдер их не вернул.

reportUrl

string | null

Ссылка на полный отчёт провайдера (если есть).

Публичная share-ссылка на отчёт (если есть).

checkedAt

string | null

ISO-8601. Когда выполнен AML-скрин. null, если проверки не было.

manualAction

string | null

Ручное действие оператора над заблокированным депозитом: release (разрешить свип) | quarantine_now.

manualActionAt

string | null

ISO-8601. Когда применено ручное действие.

manualActionReason

string | null

Причина ручного действия (комментарий оператора).

Частые ошибки

Код	HTTP	Когда возникает
`VALIDATION_FAILED`	400	тело запроса не прошло валидацию (например, отсутствует `assetCode`)
`INVALID_ASSET`	404	передан неизвестный `assetCode` (сверьтесь с `GET /v1/public/assets`)
`AMOUNT_TOO_MANY_DECIMALS`	400	в `expectedAmount` больше знаков после запятой, чем поддерживает актив
`INVALID_SIGNATURE`	401	неверная HMAC-подпись — проверьте формулу сообщения
`TIMESTAMP_SKEW`	401	`X-Timestamp` отличается от серверного более чем на 300 секунд
`IP_NOT_WHITELISTED`	403	IP сервера обменника не в белом списке
`LICENSE_REQUIRED`	403	инстанс без активной лицензии — создание депозитов недоступно
`DEPOSIT_NOT_FOUND`	404	депозит не найден или принадлежит другому сайту
`DUPLICATE_ORDER_ID`	409	`order_id` уже использован (в том числе на другой валюте)
`IDEMPOTENCY_CONFLICT`	400	тот же `X-Idempotency-Key` с другим телом запроса

Полный список кодов и формат конверта ошибки — на странице Ошибки.

Частые вопросы

Когда поле transaction перестаёт быть null?

Как только платформа замечает первую входящую транзакцию на адрес (и memo) депозита. До этого момента transaction равен null, а status остаётся check. После детекции статус переходит в process, а поля транзакции обновляются с каждым подтверждением.

Как отличить точную оплату от переплаты или недоплаты?

По финальному статусу: paid — оплачено ровно ожидаемой суммой, paid_over — больше, wrong_amount — меньше. Если expectedAmount равен "0", принимается любая сумма и исход всегда paid. Точную фактическую сумму смотрите в transaction.receivedAmount. Подробнее — в Статусах депозита.

Нужно ли опрашивать API или можно полагаться на webhooks?

Рекомендуем основным каналом сделать webhooks — платформа сама уведомит о смене статуса. GET-эндпоинты используйте как резервный механизм (для реконсиляции и при пропущенных вебхуках), опрашивая их с разумным интервалом.

Что вернётся, если повторить создание с тем же order_id?

В строгом режиме (по умолчанию) — 409 DUPLICATE_ORDER_ID, второй депозит не создаётся. Чтобы безопасно повторять запрос при сетевых сбоях, передавайте X-Idempotency-Key: при совпадении ключа и тела вернётся ранее созданный депозит. См. Идемпотентность.

Можно ли получить чужой депозит по uuid?

Нет. Все запросы скоупятся по вашему сайту. Запрос депозита, принадлежащего другому сайту, вернёт 404 DEPOSIT_NOT_FOUND — платформа не раскрывает существование чужих UUID.

См. также: Статусы депозита, Webhooks, Аутентификация, Идемпотентность, Ошибки.

​Эндпоинты

​Адрес или адрес + memo: TON против TRON/EVM

Address-based (TRON, EVM)

Memo-based (TON)

​Создать депозит

​Тело запроса

​Поля ответа

​Получить депозит

​Список депозитов

​Параметры запроса

​Поля meta

​AML-данные депозита

​Поля AML-ответа

​Частые ошибки

​Частые вопросы

Эндпоинты

Адрес или адрес + memo: TON против TRON/EVM

Создать депозит

Тело запроса

Поля ответа

Получить депозит

Список депозитов

Параметры запроса

Поля `meta`

AML-данные депозита

Поля AML-ответа

Частые ошибки

Частые вопросы