Skip to main content
Выплата — это отправка средств с вашего системного hot-кошелька на адрес получателя. Платформа сама выбирает кошелёк-источник, подписывает и отправляет транзакцию в сеть, а вы отслеживаете её по 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
Дополнительный ресурс сети: kindenergy (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.
Пример для memo-based сети (TON Jetton) — с destinationMemo:
TON Jetton
Если в ответе "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) заполняются после отправки транзакции в сеть.
Это 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: pendingmempoolconfirmed | 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 задаёте вы — это ваш ключ, по которому работает идемпотентность и поиск через by-order-id/{orderId}. Храните оба.
Передавайте X-Idempotency-Key (UUID) при создании. Повтор того же запроса с тем же ключом вернёт уже созданную выплату, а не создаст вторую. Без идемпотентного ключа повтор с тем же orderId в строгом режиме завершится 409 DUPLICATE_ORDER_ID. См. Идемпотентность.
Она ждёт ручного одобрения оператором в личном кабинете (сработала политика одобрения, лимит, белый список адресов или velocity-проверка). После одобрения статус сменится на approvedqueued и далее по потоку. Отслеживайте через вебхук или GET.
Нет, это необязательный шаг. Он удобен для предпросмотра комиссии в UI. Оценка не резервирует средства и не фиксирует точную итоговую комиссию.
После того как транзакция подписана и отправлена в сеть (статус broadcasted). До этого txHash, confirmations, networkStatus и explorerTxUrl равны null.
TON — memo-based сеть: помимо destinationAddress передавайте destinationMemo (comment), если получателю требуется метка платежа. Сумма указывается с точностью до 9 знаков.

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