uuid или по вашему order_id.
Все запросы подписываются (см. Аутентификация); ответы приходят в
конверте { "ok": true, "data": … }, ошибки — { "ok": false, "error": { "code", "message" } }.
Суммы — всегда строки, чтобы не терять точность.
Создание выплат требует API-ключа со scope
deposit_and_payout. Ключ, выданный только для
депозитов (deposit_only), получит 403 PERMISSION_DENIED. Это защита: украденный
deposit-ключ не сможет вывести средства.Эндпоинты
Рекомендуемый поток
1
Оцените комиссию
Вызовите
POST /v1/public/payouts/fee-estimate, чтобы показать клиенту комиссию сети до
подтверждения вывода. Этот вызов ничего не создаёт.2
Создайте выплату
POST /v1/public/payouts с уникальным orderId. В ответе придёт uuid и стартовый
status (queued при авто-одобрении или pending_approval, если нужно ручное одобрение).3
Отслеживайте статус
Слушайте вебхуки (
payout.broadcasted, payout.confirmed,
payout.failed) или периодически опрашивайте GET /v1/public/payouts/{uuid}.
Финальный успешный статус — confirmed.Оценить комиссию
POST /v1/public/payouts/fee-estimate — узнать комиссию сети перед созданием выплаты.
Удобно для предпросмотра суммы к списанию и UX «вы получите …».
Параметры запроса
string
required
Код актива, например
USDT_TRC20 или TON.string
required
Адрес получателя (макс. 255 символов).
string
required
Сумма выплаты строкой, например
"50.00".Поля ответа
string
Оценка комиссии сети в native-единицах сети (для TRC-20 — в TRX, для Jetton-выплат TON — в TON).
object
Дополнительный ресурс сети:
kind — energy (TRON) / gas (EVM) / bytes (UTXO) / none;
amount — оценка нужного количества этого ресурса.number
Грубая оценка времени до подтверждения (в секундах).
Создать выплату
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.destinationMemo:
TON Jetton
Получить выплату
GET /v1/public/payouts/{uuid} — по uuid из ответа на создание, либо
GET /v1/public/payouts/by-order-id/{orderId} — по вашему order_id.
Оба возвращают один и тот же объект. On-chain поля (txHash, confirmations, networkStatus,
explorerTxUrl, broadcastedAt) заполняются после отправки транзакции в сеть.
Это GET-запрос с пустым телом, поэтому подписывается строка
{timestamp}. (timestamp, затем
точка). Подробнее — в разделе Аутентификация.Поля ответа
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).
Адрес-источник (наш 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). Неизвестные значения отбрасываются.meta.total — общее число записей по всем страницам (с учётом фильтра по статусу).
Частые ошибки
Полный справочник кодов — на странице Ошибки. Ошибки аутентификации
(
UNAUTHORIZED, INVALID_SIGNATURE, TIMESTAMP_SKEW, IP_NOT_WHITELISTED) описаны в
Аутентификации.
Частые вопросы
Чем отличается uuid от order_id?
Чем отличается uuid от order_id?
uuid выдаёт платформа — это публичный идентификатор выплаты на нашей стороне. order_id
задаёте вы — это ваш ключ, по которому работает идемпотентность и поиск через
by-order-id/{orderId}. Храните оба.Как безопасно повторить запрос при таймауте?
Как безопасно повторить запрос при таймауте?
Передавайте
X-Idempotency-Key (UUID) при создании. Повтор того же запроса с тем же ключом
вернёт уже созданную выплату, а не создаст вторую. Без идемпотентного ключа повтор с тем же
orderId в строгом режиме завершится 409 DUPLICATE_ORDER_ID. См. Идемпотентность.Выплата зависла в pending_approval — что делать?
Выплата зависла в pending_approval — что делать?
Она ждёт ручного одобрения оператором в личном кабинете (сработала политика одобрения,
лимит, белый список адресов или velocity-проверка). После одобрения статус сменится на
approved → queued и далее по потоку. Отслеживайте через вебхук или GET.Нужно ли вызывать fee-estimate перед каждой выплатой?
Нужно ли вызывать fee-estimate перед каждой выплатой?
Нет, это необязательный шаг. Он удобен для предпросмотра комиссии в UI. Оценка не резервирует
средства и не фиксирует точную итоговую комиссию.
Когда txHash станет доступен?
Когда txHash станет доступен?
После того как транзакция подписана и отправлена в сеть (статус
broadcasted). До этого
txHash, confirmations, networkStatus и explorerTxUrl равны null.Что нужно для выплат в TON (Jetton)?
Что нужно для выплат в TON (Jetton)?
TON — memo-based сеть: помимо
destinationAddress передавайте destinationMemo (comment),
если получателю требуется метка платежа. Сумма указывается с точностью до 9 знаков.Смотрите также
- Статусы выплаты — жизненный цикл и какие вебхуки срабатывают.
- Вебхуки — события
payout.broadcasted,payout.confirmed,payout.failed. - Идемпотентность —
order_idиX-Idempotency-Key. - Ошибки — полный справочник кодов ответа.