Выплаты

Выплата — это отправка средств с вашего системного hot-кошелька на адрес получателя. Платформа сама выбирает кошелёк-источник, подписывает и отправляет транзакцию в сеть, а вы отслеживаете её по uuid или по вашему order_id. Все запросы подписываются (см. Аутентификация); ответы приходят в конверте { "ok": true, "data": … }, ошибки — { "ok": false, "error": { "code", "message" } }. Суммы — всегда строки, чтобы не терять точность.

Создание выплат требует API-ключа со scope deposit_and_payout. Ключ, выданный только для депозитов (deposit_only), получит 403 PERMISSION_DENIED. Это защита: украденный deposit-ключ не сможет вывести средства.

Эндпоинты

Метод	Путь	Назначение
`POST`	`/v1/public/payouts/fee-estimate`	оценить комиссию сети (без создания)
`POST`	`/v1/public/payouts`	создать выплату
`GET`	`/v1/public/payouts/{uuid}`	получить выплату по uuid
`GET`	`/v1/public/payouts/by-order-id/{orderId}`	получить выплату по вашему orderId
`GET`	`/v1/public/payouts?page=&perPage=&status=`	список (история)

Оценить комиссию

POST /v1/public/payouts/fee-estimate — узнать комиссию сети перед созданием выплаты. Удобно для предпросмотра суммы к списанию и UX «вы получите …».

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

string

required

Код актива, например USDT_TRC20 или TON.

string

required

Адрес получателя (макс. 255 символов).

string

required

Сумма выплаты строкой, например "50.00".

string

default:"recommended"

Приоритет сетевой комиссии: economy (дешевле/дольше), recommended, high (дороже/быстрее). Учитывается сетями с рынком комиссий (EVM, Bitcoin/Litecoin/Dogecoin); TRON/TON/Solana и др. игнорируют. В ответе — priority, для которого сделана оценка.

string

1.4.0. Webhook-URL именно для этой выплаты (вместо callback_url сайта). Публичный http(s)-хост.

TS=$(date +%s)
BODY='{"assetCode":"USDT_TRC20","destinationAddress":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","amount":"50.00"}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')
curl -X POST https://wallet.your-exchange.com/v1/public/payouts/fee-estimate \
  -H "X-Api-Id: $API_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" -d "$BODY"

import crypto from 'node:crypto';

const body = {
  assetCode: 'USDT_TRC20',
  destinationAddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
  amount: '50.00',
};
const raw = JSON.stringify(body);
const ts = Math.floor(Date.now() / 1000).toString();
const sig = crypto.createHmac('sha256', API_SECRET).update(`${ts}.${raw}`).digest('hex');

const res = await fetch('https://wallet.your-exchange.com/v1/public/payouts/fee-estimate', {
  method: 'POST',
  headers: {
    'X-Api-Id': API_ID,
    'X-Timestamp': ts,
    'X-Signature': sig,
    'Content-Type': 'application/json',
  },
  body: raw,
});
const { data } = await res.json();
console.log(data.networkFee, data.resource);

{
  "ok": true,
  "data": {
    "networkFee": "27.0",
    "resource": { "kind": "energy", "amount": 65000 },
    "estimatedConfirmationSeconds": 60
  }
}

Поля ответа

string

Оценка комиссии сети в native-единицах сети (для TRC-20 — в TRX, для Jetton-выплат TON — в TON).

object

Дополнительный ресурс сети: kind — energy (TRON) / gas (EVM) / bytes (UTXO) / none; amount — оценка нужного количества этого ресурса.

number

Грубая оценка времени до подтверждения (в секундах).

Оценка комиссии не резервирует средства и не гарантирует точную итоговую комиссию: реальная стоимость зависит от состояния сети на момент отправки. Используйте её для предпросмотра, а не как фиксированную величину.

Калькулятор выплаты

POST /v1/public/payouts/calculate — полная раскладка до создания: комиссия обменника, сетевая комиссия по приоритету, сколько получит адресат, сколько спишется, USD-оценки и проверки (минимум, лимиты сайта, достаточность hot-баланса). Ничего не создаёт и не резервирует.

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

string

required

Код актива.

string

required

Сумма строкой.

string

Адрес получателя — уточняет оценку сетевой комиссии.

string

default:"recommended"

economy | recommended | high.

boolean

default:"false"

true — комиссии вычитаются из amount (получатель получает меньше, списывается ровно amount); false — получатель получает ровно amount, комиссии сверху.

{
  "ok": true,
  "data": {
    "assetCode": "USDT_TRC20",
    "network": "TRON",
    "priority": "recommended",
    "isSubtract": false,
    "amount": "100.000000",
    "serviceFee": { "percent": "0.5", "amount": "0.500000", "amountUsd": "0.50" },
    "networkFee": {
      "amount": "13.5",
      "assetCode": "TRX",
      "amountUsd": "1.62",
      "estimatedConfirmationSeconds": 60,
      "error": null
    },
    "recipientReceives": "100.000000",
    "totalDebit": "100.500000",
    "amountUsd": "100.00",
    "rateUsd": "1.00",
    "minPayout": "1.000000",
    "checks": {
      "payoutEnabled": true,
      "aboveMinimum": true,
      "withinLimits": { "ok": true, "code": null, "message": null },
      "sufficientBalance": true,
      "availableBalance": "1530.500000"
    }
  }
}

totalDebit — списание в активе выплаты. Сетевая комиссия токена платится в нативной монете сети (networkFee.assetCode) и в totalDebit не входит; для нативных активов (TRX, ETH, BTC) она входит в totalDebit (или вычитается из recipientReceives при isSubtract=true). Если оценку сети получить не удалось, networkFee.amount = null, причина — в networkFee.error; остальной расчёт остаётся валидным.

Создать выплату

POST /v1/public/payouts Создаёт выплату на указанный адрес. Операция идемпотентна по паре (сайт, order_id) и, опционально, по заголовку X-Idempotency-Key. В зависимости от настроенных политик выплата может уйти в очередь сразу или потребовать ручного одобрения оператором.

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

string

required

Ваш идентификатор выплаты (1–255 символов). В строгом режиме (по умолчанию) должен быть уникальным в рамках сайта: повтор уже использованного orderId (в том числе с другим assetCode) вернёт 409 DUPLICATE_ORDER_ID — защита от случайной двойной выплаты. Для безопасных ретраев используйте X-Idempotency-Key (см. Идемпотентность).

string

required

Код актива, например USDT_TRC20 или TON (макс. 64 символа).

string

required

Адрес получателя (макс. 255 символов). Проверяется и нормализуется по правилам сети.

string

Memo/comment для memo-based сетей (например TON Jetton). Для account-based сетей (TRON, EVM) не используется. Опционально, макс. 255 символов.

string

required

Сумма выплаты строкой, например "50.00". Число знаков после запятой не должно превышать точность актива (USDT_TRC20 — 6, TON — 9), иначе INVALID_AMOUNT / VALIDATION_FAILED.

string

default:"recommended"

Приоритет сетевой комиссии: economy | recommended | high. Сохраняется в выплате и применяется при построении транзакции (EVM gas-тиры, UTXO sat/vB). Сети без рынка комиссий игнорируют. См. Комиссии и лимиты.

Массовое создание

POST /v1/public/payouts/bulk — до 100 выплат за запрос, тело { "items": [ …параметры создания… ] }. Каждая строка обрабатывается независимо: ошибка одной не отменяет остальные. Идемпотентность — по orderId каждой строки (X-Idempotency-Key на весь пакет не применяется). Требует scope deposit_and_payout.

{
  "ok": true,
  "data": {
    "items": [
      { "index": 0, "ok": true, "orderId": "batch-1", "payout": { "uuid": "…", "status": "queued" }, "error": null },
      { "index": 1, "ok": false, "orderId": "batch-2", "payout": null,
        "error": { "code": "INVALID_ADDRESS", "message": "Invalid address for TRON" } }
    ],
    "summary": { "total": 2, "succeeded": 1, "failed": 1 }
  }
}

TS=$(date +%s)
BODY='{"orderId":"order_77","assetCode":"USDT_TRC20","destinationAddress":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","amount":"50.00"}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')
curl -X POST https://wallet.your-exchange.com/v1/public/payouts \
  -H "X-Api-Id: $API_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "X-Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" -d "$BODY"

import crypto from 'node:crypto';
import { randomUUID } from 'node:crypto';

const body = {
  orderId: 'order_77',
  assetCode: 'USDT_TRC20',
  destinationAddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
  amount: '50.00',
};
const raw = JSON.stringify(body);
const ts = Math.floor(Date.now() / 1000).toString();
const sig = crypto.createHmac('sha256', API_SECRET).update(`${ts}.${raw}`).digest('hex');

const res = await fetch('https://wallet.your-exchange.com/v1/public/payouts', {
  method: 'POST',
  headers: {
    'X-Api-Id': API_ID,
    'X-Timestamp': ts,
    'X-Signature': sig,
    'X-Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: raw,
});
const { ok, data, error } = await res.json();

Пример для memo-based сети (TON Jetton) — с destinationMemo:

TON Jetton

{
  "orderId": "order_78",
  "assetCode": "USDT_TON",
  "destinationAddress": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "destinationMemo": "WP-90AB12CD",
  "amount": "25.00"
}

{
  "ok": true,
  "data": {
    "uuid": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "orderId": "order_77",
    "status": "queued",
    "assetCode": "USDT_TRC20",
    "destinationAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "destinationMemo": null,
    "amount": "50.000000",
    "requiresApproval": false,
    "txHash": null,
    "confirmations": null,
    "requiredConfirmations": null,
    "networkStatus": null,
    "explorerTxUrl": null,
    "failReason": null,
    "approvedAt": null,
    "broadcastedAt": null,
    "confirmedAt": null,
    "createdAt": "2026-06-02T20:50:00.000Z",
    "updatedAt": "2026-06-02T20:50:00.000Z"
  }
}

Если в ответе "requiresApproval": true и "status": "pending_approval" — выплата ждёт ручного одобрения оператором в личном кабинете и уйдёт в сеть только после него. Это защита от ошибочных крупных выводов и срабатывание политик (лимиты, белый список адресов, velocity-проверки). Отслеживайте статус через GET или вебхуки.

Получить выплату

GET /v1/public/payouts/{uuid} — по uuid из ответа на создание, либо GET /v1/public/payouts/by-order-id/{orderId} — по вашему order_id. Оба возвращают один и тот же объект. On-chain поля (txHash, confirmations, networkStatus, explorerTxUrl, broadcastedAt) заполняются после отправки транзакции в сеть.

TS=$(date +%s)
SIG=$(printf '%s.' "$TS" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')
curl https://wallet.your-exchange.com/v1/public/payouts/c1d2e3f4-5678-90ab-cdef-1234567890ab \
  -H "X-Api-Id: $API_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

TS=$(date +%s)
SIG=$(printf '%s.' "$TS" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')
curl https://wallet.your-exchange.com/v1/public/payouts/by-order-id/order_77 \
  -H "X-Api-Id: $API_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Это GET-запрос с пустым телом, поэтому подписывается строка {timestamp}. (timestamp, затем точка). Подробнее — в разделе Аутентификация.

{
  "ok": true,
  "data": {
    "uuid": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "orderId": "order_77",
    "status": "broadcasted",
    "assetCode": "USDT_TRC20",
    "destinationAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "destinationMemo": null,
    "amount": "50.000000",
    "requiresApproval": false,
    "txHash": "f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9",
    "confirmations": 12,
    "requiredConfirmations": 19,
    "networkStatus": "mempool",
    "explorerTxUrl": "https://tronscan.org/#/transaction/f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9",
    "failReason": null,
    "approvedAt": null,
    "broadcastedAt": "2026-06-02T20:51:10.000Z",
    "confirmedAt": null,
    "createdAt": "2026-06-02T20:50:00.000Z",
    "updatedAt": "2026-06-02T20:51:10.000Z"
  }
}

Поля ответа

string

Публичный идентификатор выплаты (UUID).

string

Ваш order_id, переданный при создании.

string

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

string

Код актива.

string

Адрес получателя (в нормализованной форме сети).

string | null

Memo получателя для memo-based сетей, иначе null.

string

Сумма выплаты строкой, отформатированная под точность актива.

boolean

Требуется ли ручное одобрение оператором.

string | null

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

number | null

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

number | null

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

string | null

On-chain статус исходящей tx: pending → mempool → confirmed | fail. null до отправки.

string | null

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

string | null

Причина для терминальных статусов failed / rejected / cancelled, иначе null.

string | null

Когда выплата одобрена оператором (ISO-8601). null при авто-одобрении или до одобрения.

string | null

Когда транзакция отправлена в сеть (ISO-8601). null до отправки.

string | null

Когда выплата подтверждена сетью (ISO-8601). null до подтверждения.

string

Время создания выплаты (ISO-8601).

string

Время последнего обновления (ISO-8601).

string

Сеть актива (TRON, ETHEREUM, …).

boolean

Терминальный ли статус (confirmed / failed / rejected / cancelled) — можно прекращать поллинг.

string

Приоритет сетевой комиссии, выбранный при создании.

string | null

Оценка суммы в USD по курсу на момент ответа (2 знака). null, если курса нет.

string | null

Курс актива к USD на момент ответа.

string | null

Комиссия обменника (ledger), если учёт комиссий включён и выплата подтверждена.

string | null

Фактическая сетевая комиссия исходящей tx в нативной монете сети. null, пока неизвестна.

Адрес-источник (наш hot-кошелёк), внутренние идентификаторы и приватные ключи наружу не отдаются — только то, что нужно для отслеживания исходящей транзакции.

Список выплат

GET /v1/public/payouts?page=1&perPage=20&status=confirmed История выплат сайта с пагинацией. Доступна только тем выплатам, что принадлежат сайту вызывающего ключа.

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

number

default:"1"

Номер страницы (с 1).

number

default:"20"

Размер страницы (макс. 100).

string

Фильтр по статусу. Одно значение (?status=confirmed) или несколько через запятую (?status=queued,broadcasted). Неизвестные значения отбрасываются.

string

Keyset-пагинация: курсор из meta.nextCursor предыдущего ответа. Первую страницу по курсору запрашивайте с пустым cursor= — тогда meta.nextCursor появится в ответе (null — конец). При наличии cursor параметр page игнорируется. Выдача по курсору не сдвигается при появлении новых выплат — ни пропусков, ни дублей при обходе истории.

{
  "ok": true,
  "data": {
    "items": [
      {
        "uuid": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
        "orderId": "order_77",
        "status": "confirmed",
        "assetCode": "USDT_TRC20",
        "destinationAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "destinationMemo": null,
        "amount": "50.000000",
        "requiresApproval": false,
        "txHash": "f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9",
        "confirmations": 19,
        "requiredConfirmations": 19,
        "networkStatus": "confirmed",
        "explorerTxUrl": "https://tronscan.org/#/transaction/f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9",
        "failReason": null,
        "approvedAt": null,
        "broadcastedAt": "2026-06-02T20:51:10.000Z",
        "confirmedAt": "2026-06-02T20:53:40.000Z",
        "createdAt": "2026-06-02T20:50:00.000Z",
        "updatedAt": "2026-06-02T20:53:40.000Z"
      }
    ],
    "meta": { "page": 1, "perPage": 20, "total": 58 }
  }
}

meta.total — общее число записей по всем страницам (с учётом фильтра по статусу).

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

HTTP	Код	Причина
403	`PERMISSION_DENIED`	Ключ выдан только для депозитов (`deposit_only`) — создание выплат запрещено. Используйте ключ со scope `deposit_and_payout`.
409	`DUPLICATE_ORDER_ID`	`orderId` уже использован для этого сайта (строгий режим). Для ретраев применяйте `X-Idempotency-Key`.
404	`INVALID_ASSET`	Указанный `assetCode` не найден.
409	`NETWORK_DISABLED`	Выплаты по этому активу выключены или актив неактивен.
400	`INVALID_ADDRESS`	Адрес получателя не проходит валидацию для сети актива.
400	`INVALID_AMOUNT`	Сумма не положительная или с недопустимым числом знаков после запятой.
409	`AMOUNT_BELOW_MINIMUM`	Сумма ниже минимальной выплаты для актива.
400	`PAYOUT_DESTINATION_BLACKLISTED`	Адрес получателя в чёрном списке — выплата запрещена.
400	`PAYOUT_WHITELIST_REJECT`	Адрес не в белом списке вывода (режим enforced).
400	`PAYOUT_VELOCITY_REJECT`	Превышены velocity-лимиты (частота/объём выплат).
404	`PAYOUT_NOT_FOUND`	Выплата с таким `uuid` / `orderId` не найдена для этого сайта.
403	`LICENSE_REQUIRED`	Лицензия инстанса неактивна — создание новых выплат недоступно. Уже одобренные и поставленные в очередь выплаты не затрагиваются.

Полный справочник кодов — на странице Ошибки. Ошибки аутентификации (UNAUTHORIZED, INVALID_SIGNATURE, TIMESTAMP_SKEW, IP_NOT_WHITELISTED) описаны в Аутентификации.

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

Чем отличается uuid от order_id?

uuid выдаёт платформа — это публичный идентификатор выплаты на нашей стороне. order_id задаёте вы — это ваш ключ, по которому работает идемпотентность и поиск через by-order-id/{orderId}. Храните оба.

Как безопасно повторить запрос при таймауте?

Передавайте X-Idempotency-Key (UUID) при создании. Повтор того же запроса с тем же ключом вернёт уже созданную выплату, а не создаст вторую. Без идемпотентного ключа повтор с тем же orderId в строгом режиме завершится 409 DUPLICATE_ORDER_ID. См. Идемпотентность.

Выплата зависла в pending_approval — что делать?

Она ждёт ручного одобрения оператором в личном кабинете (сработала политика одобрения, лимит, белый список адресов или velocity-проверка). После одобрения статус сменится на approved → queued и далее по потоку. Отслеживайте через вебхук или GET.

Нужно ли вызывать fee-estimate перед каждой выплатой?

Нет, это необязательный шаг. Он удобен для предпросмотра комиссии в UI. Оценка не резервирует средства и не фиксирует точную итоговую комиссию. Для полного предпросмотра «сколько получит / сколько спишется» с учётом комиссии обменника и проверок лимитов используйте POST /v1/public/payouts/calculate.

Когда выбирать priority=economy или high?

economy — некритичные по времени выплаты в EVM/UTXO-сетях (ниже tip / sat/vB, подтверждение дольше). high — когда важна скорость (попасть в ближайший блок). В сетях без рынка комиссий (TRON, TON, Solana, Cosmos, Polkadot) приоритет ничего не меняет. Актуальные значения по трём уровням — в GET /v1/public/fees.

Когда txHash станет доступен?

После того как транзакция подписана и отправлена в сеть (статус broadcasted). До этого txHash, confirmations, networkStatus и explorerTxUrl равны null.

Что нужно для выплат в TON (Jetton)?

TON — memo-based сеть: помимо destinationAddress передавайте destinationMemo (comment), если получателю требуется метка платежа. Сумма указывается с точностью до 9 знаков.

Смотрите также

Статусы выплаты — жизненный цикл и какие вебхуки срабатывают.
Вебхуки — события payout.broadcasted, payout.confirmed, payout.failed.
Идемпотентность — order_id и X-Idempotency-Key.
Ошибки — полный справочник кодов ответа.

Начало работы

Аутентификация

Депозиты

Совместимость

Счета

Webhooks

AML

Конвертации

Справочник

Выплаты — отправка платежей

Эндпоинты

Рекомендуемый поток

Оценить комиссию

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

Поля ответа

Калькулятор выплаты

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

Создать выплату

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

Массовое создание

Получить выплату

Поля ответа

Список выплат

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

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

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

Смотрите также

​Эндпоинты

​Рекомендуемый поток

​Оценить комиссию

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

​Поля ответа

​Калькулятор выплаты

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

​Создать выплату

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

​Массовое создание

​Получить выплату

​Поля ответа

​Список выплат

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

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

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

​Смотрите также

Эндпоинты

Рекомендуемый поток

Оценить комиссию

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

Поля ответа

Калькулятор выплаты

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

Создать выплату

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

Массовое создание

Получить выплату

Поля ответа

Список выплат

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

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

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

Смотрите также