---
title: "Create Payout"
method: POST
path: "/payouts"
tags: ["Payouts"]
---

# Create Payout

`POST /payouts`

Sends money from an account or user balance to a saved payout method for that owner.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `account_id` string, required — Account to pay out from, prefixed `biz_`. Provide exactly one of `account_id` or `user_id`.
    - `acknowledge_bank_warning` boolean — Set to `true` to continue when the destination bank could not confirm the payout method account holder's name, or `false` to have the payout refused in that case so the account holder can correct the name or link their bank first. Omitting the field skips the warning gate — a client that cannot show the warning keeps its pre-gate behavior.
    - `amount` number, float, required — The amount to pay out in the specified currency.
    - `currency` string — The currency to pay out. Balances are held per currency and the payout draws only from the balance in this currency, so match the currency the funds arrived in — for example `cad` for an account funded by CAD transfers. Defaults to `usd`.
    - `metadata` object — Key-value data to attach to the payout, echoed on every read and in webhook payloads. At most 50 keys, key names up to 40 characters, string values up to 500 characters. Never store secrets or regulated personal data here — webhook bodies are retained for delivery inspection.
    - `notes` string, nullable — Free-form notes to attach to the payout, with a maximum of 255 characters. Omit or pass `null` for no notes.
    - `payout_method_id` string, required — The saved payout method to deliver to (a potk_ identifier).
    - `platform_covers_fees` boolean — Whether the parent platform covers the payout fee instead of the account being paid out. Omit to use the platform's configured fee coverage policy; pass `false` to opt out of it. `true` is only accepted for accounts that belong to a platform, and requires the platform's policy to cover this payout method's category or a caller authorized to manage the platform's child account fees.
    - `speed` 'standard' | 'instant' — How fast the funds should arrive. `instant` is only accepted when the account and payout method are eligible; otherwise the payout is rejected.
    - `user_id` string — User to pay out from, prefixed `user_`. Provide exactly one of `account_id` or `user_id`.
  - object
    - `account_id` string — Account to pay out from, prefixed `biz_`. Provide exactly one of `account_id` or `user_id`.
    - `acknowledge_bank_warning` boolean — Set to `true` to continue when the destination bank could not confirm the payout method account holder's name, or `false` to have the payout refused in that case so the account holder can correct the name or link their bank first. Omitting the field skips the warning gate — a client that cannot show the warning keeps its pre-gate behavior.
    - `amount` number, float, required — The amount to pay out in the specified currency.
    - `currency` string — The currency to pay out. Balances are held per currency and the payout draws only from the balance in this currency, so match the currency the funds arrived in — for example `cad` for an account funded by CAD transfers. Defaults to `usd`.
    - `metadata` object — Key-value data to attach to the payout, echoed on every read and in webhook payloads. At most 50 keys, key names up to 40 characters, string values up to 500 characters. Never store secrets or regulated personal data here — webhook bodies are retained for delivery inspection.
    - `notes` string, nullable — Free-form notes to attach to the payout, with a maximum of 255 characters. Omit or pass `null` for no notes.
    - `payout_method_id` string, required — The saved payout method to deliver to (a potk_ identifier).
    - `platform_covers_fees` boolean — Whether the parent platform covers the payout fee instead of the account being paid out. Omit to use the platform's configured fee coverage policy; pass `false` to opt out of it. `true` is only accepted for accounts that belong to a platform, and requires the platform's policy to cover this payout method's category or a caller authorized to manage the platform's child account fees.
    - `speed` 'standard' | 'instant' — How fast the funds should arrive. `instant` is only accepted when the account and payout method are eligible; otherwise the payout is rejected.
    - `user_id` string, required — User to pay out from, prefixed `user_`. Provide exactly one of `account_id` or `user_id`.

## Response `201`

payout created

- object
  - `amount` string, decimal, required — The payout amount in whole currency units, as a decimal string.
  - `created_at` string, date-time, required — When the payout was created.
  - `currency` string, required — Payout currency.
  - `destination_amount` string, decimal, nullable, required — The amount delivered in the destination currency, as a decimal string. Null until the payout settles; appears on the payout in GET /payouts once assigned.
  - `destination_currency` string, nullable, required — Currency the funds are delivered in, taken from the payout method. On a stablecoin payout it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.
  - `estimated_arrival` string, date-time, nullable, required — Estimated time the funds become available in the destination account. Null until the payout settles.
  - `exchange_rate` number, float, nullable, required — Exchange rate from the payout currency to the destination currency. Null until the payout settles; appears on the payout in GET /payouts once assigned.
  - `failure` object, nullable, required — Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.
    - `code` string, nullable, required — Classified failure code from the maintained error catalog.
    - `funds_returned_at` string, date-time, nullable, required — The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.
    - `message` string, nullable, required — Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.
  - `fee_amount` string, decimal, required — The fee charged for the payout, in the payout currency, as a decimal string.
  - `fee_paid_by` 'self' | 'platform', required — Who bore the payout fee: the account itself, or its parent platform.
  - `id` string, required — Payout ID, prefixed `wdrl_` — the id POST returns is the id GET /payouts lists. Conversion requests created before this version keep answering under their `cofr_` id.
  - `markup_fee` string, decimal, required — Whop's markup on the provider fee, in the payout currency, as a decimal string. `"0.0"` when none applies.
  - `metadata` object, required — Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.
  - `net_amount` string, decimal, required — The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled stablecoin payout can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.
  - `notes` string, nullable, required — Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.
  - `object` 'payout', required
  - `payer_name` string, nullable, required — Name of the entity processing the payout. Null until the payout settles.
  - `payout_method` object, nullable, required — The saved payout method used. Requires payout:destination:read; null without it.
    - `nickname` string, nullable, required — Saved payout method nickname.
    - `supported_payout_method` object, nullable, required — Supported payout method display details.
      - `delivery_type` 'cash_pickup' | 'bank_deposit' | 'home_delivery' | 'mobile_wallet' | 'masspay_card' | 'paper_check' | 'bill' | 'cryptocurrency' | 'unknown', required — How the funds are delivered to the recipient.
      - `icon_url` string, nullable, required — Supported payout method icon URL.
      - `payer_name` string, nullable, required — Supported payout method display name.
  - `payout_request_id` string, nullable, required — For a stablecoin payout, the id of the conversion request that funds it, prefixed `cofr_`; `null` on fiat payouts.
  - `source` 'api' | 'dashboard' | 'automatic' | 'null', nullable, required — How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.
  - `speed` 'standard' | 'instant', required — Payout delivery speed.
  - `status` 'requested' | 'in_review' | 'processing' | 'completed' | 'reversed' | 'canceled' | 'failed' | 'denied', required — Current payout status, in the same vocabulary as GET /payouts.
  - `status_detail` string, required — The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the stablecoin conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.
  - `trace_code` string, nullable, required — ACH trace number the recipient's bank can use to locate this payout. Always `null` here — it is assigned when the payout is submitted to the bank, and appears on the payout in GET /payouts once it has been sent; payouts not sent over ACH never get one.

## Other responses

- `400` — Invalid Parameters
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Resource not found
- `409` — Conflict

---

[API](https://skmtc.net/whop/apis/whop-api.md) · [All operations](https://skmtc.net/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/whop/whop-api/revisions/715c4defcbbf/schema)