> ## Documentation Index
> Fetch the complete documentation index at: https://oblodai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

Справочник метода — [`POST /v1/payout`](/reference/payout-create).

***

## Поток

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

***

<Steps>
  <Step title="Проверить баланс" titleSize="h2">
    <CodeGroup>
      ```python Python theme={null}
      bal = call("/v1/balance", {})["result"]["balance"]["merchant"]
      # [{"currency": "USDT", "balance": "1240.75"}, ...]
      ```

      ```js Node.js theme={null}
      const bal = (await call("/v1/balance", {})).result.balance.merchant;
      // [{"currency": "USDT", "balance": "1240.75"}, ...]
      ```
    </CodeGroup>

    <Warning>
      **Осторожно с незрелыми средствами.** Свежий депозит виден в балансе, но до набора подтверждений
      находится под maturity‑холдом и **не выводим**. Выплата на сумму, включающую незрелые средства,
      вернёт `409 payout.funds_maturing`. Выводимый остаток может быть временно меньше показанного. См.
      [`POST /v1/balance`](/reference/balance).
    </Warning>
  </Step>

  <Step title="Посчитать комиссию (необязательно)" titleSize="h2">
    Чтобы заранее понять, сколько уйдёт с баланса и сколько получит адрес:

    <CodeGroup>
      ```python Python theme={null}
      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"}
      ```

      ```js Node.js theme={null}
      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"}
      ```
    </CodeGroup>

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

    <Note>
      `is_subtract` здесь — параметр **предрасчёта** `calculate`. На самой выплате `/v1/payout` это поле не
      действует: кто платит сетевую комиссию, определяет настройка проекта
      [`fee-config`](/reference/payout-fee-config). Считайте `calculate` с тем же вариантом, что стоит
      в fee‑config, — тогда превью совпадёт с реальной выплатой.
    </Note>
  </Step>

  <Step title="Создать выплату" titleSize="h2">
    <CodeGroup>
      ```python Python theme={null}
      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 — подтверждение не нужно
      ```

      ```js Node.js theme={null}
      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 — подтверждение не нужно
      ```
    </CodeGroup>

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

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

    Как добавить заголовок в свою обёртку `call()` — [Устойчивый
    клиент](/guides/resilient-client#главный-принцип).
  </Step>

  <Step title="Отследить статус" titleSize="h2">
    Статус выплаты в ответах — укрупнённый ([маппинг](/reference/payout-object#статусы-выплаты)):

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

    Финал — `is_final: true` (`paid`/`fail`/`cancel`). О смене статуса приходит вебхук `payout.*` — ловите
    его так же, как платёжный (проверка подписи, идемпотентность). См.
    [Настройка вебхуков](/guides/webhooks-setup).
  </Step>
</Steps>

***

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

| Код                               | Что значит                                       | Что делать                                                                                                |
| --------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `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`     | Сумма меньше комиссии сети.                      | Увеличить сумму.                                                                                          |

<Warning>
  **`409` ≠ «всё, выплата отменена».** Не бросайте выплату при первом же `409`:
  `payout.funds_maturing` и `idempotency.in_progress` **надо повторить позже**, и деньги уйдут. Разбор —
  [Устойчивый клиент](/guides/resilient-client#не-все-409-финальны).
</Warning>

***

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

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

* Включить [IP‑allowlist](/reference/api-allowlist), чтобы выплаты можно было инициировать только
  с вашего backend.
* Хранить `secret` только на сервере.
* Валидировать адрес получателя на своей стороне до вызова.

См. [Безопасность в проде](/guides/production-security).

***

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

<CardGroup cols={2}>
  <Card title="POST /v1/payout" href="/reference/payout-create" icon="arrow-right" horizontal />

  <Card title="Объект выплаты" href="/reference/payout-object" icon="arrow-right" horizontal />

  <Card title="POST /v1/payout/calculate" href="/reference/payout-calculate" icon="arrow-right" horizontal />

  <Card title="POST /v1/balance" href="/reference/balance" icon="arrow-right" horizontal />

  <Card title="Модель баланса и движение средств" href="/guides/balance-and-funds" icon="arrow-right" horizontal />

  <Card title="Рецепт устойчивого клиента" href="/guides/resilient-client" icon="arrow-right" horizontal />

  <Card title="Массовые операции" href="/guides/batch-operations" icon="arrow-right" horizontal />

  <Card title="Массовые выплаты" href="/guides/mass-payouts" icon="arrow-right" horizontal />

  <Card title="Сплит‑платежи" href="/guides/split-payments" icon="arrow-right" horizontal />

  <Card title="Возвраты платежей" href="/guides/refunds" icon="arrow-right" horizontal />
</CardGroup>