Первая выплата

Выплата — это вывод средств с вашего баланса на внешний адрес. По API‑ключу выплата авто‑одобряется и уходит сразу, без белых списков и периодов выдержки. Разберём поток от проверки баланса до подтверждающего вебхука.

Справочник метода — POST /v1/payout.

---

​

Поток

1. Проверяете баланс (POST /v1/balance)
2. (опц.) Считаете комиссию заранее (POST /v1/payout/calculate)
3. Создаёте выплату (POST /v1/payout) — уходит сразу
4. Ловите вебхук payout.* о подтверждении

---

1. Проверить баланс

   Python

   bal = call("/v1/balance", {})["result"]["balance"]["merchant"]
   # [{"currency": "USDT", "balance": "1240.75"}, ...]
   

   const bal = (await call("/v1/balance", {})).result.balance.merchant;
   // [{"currency": "USDT", "balance": "1240.75"}, ...]
   

   Осторожно с незрелыми средствами. Свежий депозит виден в балансе, но до набора подтверждений находится под maturity‑холдом и не выводим. Выплата на сумму, включающую незрелые средства, вернёт 409 payout.funds_maturing. Выводимый остаток может быть временно меньше показанного. См. POST /v1/balance.

2. Посчитать комиссию (необязательно)

   Чтобы заранее понять, сколько уйдёт с баланса и сколько получит адрес:

   Python

   calc = call("/v1/payout/calculate", {
       "amount": "25", "currency": "USDT", "network": "tron", "is_subtract": False,
   })["result"]
   # {"commission": "1.1", "merchant_amount": "25", "to_amount": "23.9"}
   

   const calc = (await call("/v1/payout/calculate", {
     amount: "25", currency: "USDT", network: "tron", is_subtract: false,
   })).result;
   // {"commission": "1.1", "merchant_amount": "25", "to_amount": "23.9"}
   

   • is_subtract: false — комиссия из суммы (получатель получает меньше).
   • is_subtract: true — комиссия сверх суммы (списывается с баланса дополнительно).

   is_subtract здесь — параметр предрасчёта calculate. На самой выплате /v1/payout это поле не действует: кто платит сетевую комиссию, определяет настройка проекта fee-config. Считайте calculate с тем же вариантом, что стоит в fee‑config, — тогда превью совпадёт с реальной выплатой.

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

   Python

   import uuid
   
   key = str(uuid.uuid4())          # Idempotency-Key: ОДИН на действие, не меняется при ретраях
   
   payout = call("/v1/payout", {
       "amount": "25",
       "currency": "USDT",
       "network": "tron",           # обязательна для монет с несколькими сетями
       "address": "TXY...",
       "order_id": "payout-1",      # ОБЯЗАТЕЛЬНО для выплаты — ваш бизнес-ключ
   }, idempotency_key=key)["result"]
   
   print(payout["status"])          # "process" — уже отправляется
   print(payout["approval_required"])  # false — подтверждение не нужно
   

   import { randomUUID } from "node:crypto";
   
   const key = randomUUID();        // Idempotency-Key: ОДИН на действие, не меняется при ретраях
   
   const payout = (await call("/v1/payout", {
     amount: "25",
     currency: "USDT",
     network: "tron",             // обязательна для монет с несколькими сетями
     address: "TXY...",
     order_id: "payout-1",        // ОБЯЗАТЕЛЬНО для выплаты — ваш бизнес-ключ
   }, key)).result;               // key → заголовок Idempotency-Key в вашей обёртке call()
   
   console.log(payout.status);             // "process" — уже отправляется
   console.log(payout.approval_required);  // false — подтверждение не нужно
   

   Выплата — самая дорогая операция для дубля, поэтому здесь работают оба механизма защиты:

   • Idempotency-Key (HTTP‑заголовок) — генерируется до первой отправки и одинаков во всех ретраях. Повтор с тем же ключом вернёт тот же ответ и заголовок Idempotent-Replayed: true. Если предыдущая попытка ещё выполняется — придёт 409 idempotency.in_progress: подождите и повторите.
   • order_id — для выплаты обязателен (без него 400 payout.order_id_required). Повтор с тем же order_id вернёт уже созданную выплату, а не отправит вторую.

   Как добавить заголовок в свою обёртку call() — Устойчивый клиент.

4. Отследить статус

   Статус выплаты в ответах — укрупнённый (маппинг):

   status	Значение
   check	Создана, средства зарезервированы, ждёт одобрения.
   process	Одобрена / отправляется / отправлена, ждёт подтверждений.
   paid	Подтверждена в блокчейне — готово.
   fail	Отклонена / отправка не удалась, резерв освобождён.
   cancel	Отменена до отправки, резерв освобождён.

   Финал — is_final: true (paid/fail/cancel). О смене статуса приходит вебхук payout.* — ловите его так же, как платёжный (проверка подписи, идемпотентность). См. Настройка вебхуков.

---

​

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

Код	Что значит	Что делать
409 payout.insufficient_funds	Недостаточно доступного баланса.	Пополнить баланс или уменьшить сумму. Повтор не поможет.
409 payout.funds_maturing	Средства ещё дозревают.	Повторить позже — это временная ошибка, а не отказ. Или вывести меньшую сумму (без свежих депозитов).
409 idempotency.in_progress	Запрос с этим Idempotency-Key ещё выполняется.	Подождать и повторить — получите результат первой попытки.
400 payout.destination_internal	Адрес принадлежит шлюзу.	Указать внешний адрес.
400 payout.order_id_required	Не передан order_id.	Всегда задавайте order_id.
400 payout.amount_below_fee	Сумма меньше комиссии сети.	Увеличить сумму.

409 ≠ «всё, выплата отменена». Не бросайте выплату при первом же 409: payout.funds_maturing и idempotency.in_progress надо повторить позже, и деньги уйдут. Разбор — Устойчивый клиент.

---

​

Важно про безопасность

Выплаты по API‑ключу уходят сразу и необратимы. Ответственность за адрес назначения — на вашей стороне. Рекомендуется:

• Включить IP‑allowlist, чтобы выплаты можно было инициировать только с вашего backend.
• Хранить secret только на сервере.
• Валидировать адрес получателя на своей стороне до вызова.

См. Безопасность в проде.

---

​

Связанные страницы

POST /v1/payout

Объект выплаты

POST /v1/payout/calculate

POST /v1/balance

Модель баланса и движение средств

Рецепт устойчивого клиента

Массовые операции

Массовые выплаты

Сплит‑платежи

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