POST /v1/payout

Создать выплату на внешний адрес. Списывает баланс на amount; получателю приходит amount минус сетевая комиссия (если она переложена на получателя — см. fee-config).

URL: https://api.oblodai.com/v1/payout · Аутентификация: обязательна · Идемпотентность: заголовок Idempotency-Key и/или order_id (для выплат order_id обязателен).

Примеры используют хелпер call() и переменные $SECRET/$PUBLIC_ID — их определение см. в Как подписать запрос. Проще не писать подпись руками, а взять SDK.

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

​

Заголовки

Idempotency-Key

Любое уникальное значение (≤255 символов), одинаковое во всех повторах одной выплаты. Повтор вернёт тот же ответ и заголовок Idempotent-Replayed: true. Работает вместе с order_id. → Идемпотентность

---

​

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

amount · string · обязательно

Сумма выплаты в currency.

currency · string · обязательно

Код валюты (например USDT).

order_id · string · обязательно

Ваш номер выплаты; ключ идемпотентности.

address · string · обязательно

Адрес получателя.

network · string

Сеть (tron, ethereum, …). Обязательна для монет с несколькими сетями.

is_subtract · bool

Кто платит сетевую комиссию. true — комиссия сверх суммы: с баланса списывается amount + fee, получатель получает ровно amount. false — комиссия из суммы: списывается amount, получатель получает amount − fee. Не передано — действует fee-config проекта (иначе дефолт шлюза). Семантика совпадает с предрасчётом /v1/payout/calculate.

memo · string

Тег/мемо назначения (TON Jetton). Максимум 120 символов.

url_callback · string

Свой URL вебхука для этой выплаты (SSRF‑проверка).

from_currency · string

Профинансировать выплату конвертацией баланса. Поддерживается только USDT → currency.

source · string · по умолчанию: "api"

Метка происхождения: api (по умолчанию) или manual.

По умолчанию сетевую комиссию выплаты несёт получатель. Кто её платит, определяется настройкой проекта fee-config (общий дефолт — комиссию несёт получатель), а не полем запроса.

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

---

​

Пример запроса

cURL

BODY='{"amount":"25","currency":"USDT","network":"tron","address":"TXY...","order_id":"payout-1"}'
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" 'POST' '/v1/payout' "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -s https://api.oblodai.com/v1/payout \
  -X POST -H 'Content-Type: application/json' \
  -H "X-Public-Id: $PUBLIC_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d "$BODY"

call("/v1/payout", {
    "amount": "25", "currency": "USDT", "network": "tron",
    "address": "TXY...", "order_id": "payout-1",
})

await call("/v1/payout", {
  amount: "25", currency: "USDT", network: "tron",
  address: "TXY...", order_id: "payout-1",
});

---

​

Пример ответа

{
  "state": 0,
  "result": {
    "uuid": "0c1f...e9",
    "order_id": "payout-1",
    "amount": "25",
    "currency": "USDT",
    "network": "tron",
    "address": "TXY...",
    "txid": "",
    "status": "process",
    "is_final": false,
    "approval_required": false,
    "source": "api",
    "created_at": "2026-07-10T12:00:00Z",
    "updated_at": "2026-07-10T12:00:00Z"
  }
}

При from_currency в result добавляется объект convert:

{ "from_currency": "USDT", "to_currency": "TRX", "from_amount": "40.12", "rate": "0.062" }

Полное описание полей и статусов — Объект выплаты.

---

​

Коды ошибок

Код	Значение
400 payout.unknown_currency	Неизвестная валюта.
400 payout.bad_amount	Некорректная сумма.
400 payout.order_id_required	Не передан order_id.
400 payout.destination_internal	Адрес принадлежит шлюзу (self‑dealing).
400 payout.from_currency_unsupported	Неподдерживаемая конвертация.
400 payout.memo_too_long	memo длиннее 120 символов.
400 payout.bad_url_callback	Некорректный url_callback (SSRF).
400 payout.no_destination	Не передан адрес назначения.
400 payout.asset_mismatch	Валюта/сеть не соответствуют друг другу.
400/403	Валидация адреса под сеть / комплаенс.
409 payout.frozen	Выплаты заморожены (сработал kill‑switch).
409 payout.insufficient_funds	Недостаточно доступного баланса.
409 payout.funds_maturing	Средства ещё дозревают (maturity‑холд).

---

​

Нюансы

• Идемпотентность по (мерчант, order_id). Повтор вернёт уже созданную выплату.
• Выплата на адрес самого шлюза запрещена (payout.destination_internal).
• from_currency конвертирует баланс до резервирования и идемпотентна по order_id. Поддерживается только USDT → currency.
• Выплаты по API‑ключу авто‑одобряются (approval_required: false) — шаг /approve не нужен.
• Перед созданием можно оценить комиссию и итоговые суммы через POST /v1/payout/calculate.
• Много выплат? → POST /v1/payout/batch — до 5000 одним запросом.

---

​

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

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

POST /v1/payout/calculate

POST /v1/payout/batch

Много выплат сразу — до 5000 одним запросом.

POST /v1/payout/mass (легаси, до 100)

Кто платит сетевую комиссию

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