Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

Headers

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-08-21"

Body

application/json
account_id
string
required

Account to pay out from, prefixed biz_. Provide exactly one of account_id or user_id.

Example:

"biz_xxxxxxxxxxxxxx"

amount
number<float>
required

The amount to pay out in the specified currency.

Example:

50

payout_method_id
string
required

The saved payout method to deliver to (a potk_ identifier).

Example:

"potk_xxxxxxxxxxxxxx"

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.

Example:

true

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.

Example:

"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.

Example:
notes
string | null

Free-form notes to attach to the payout, with a maximum of 255 characters. Omit or pass null for no notes.

Maximum string length: 255
Example:

"Detailing supplies restock"

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.

Example:

true

speed
enum<string>
default:standard

How fast the funds should arrive. instant is only accepted when the account and payout method are eligible; otherwise the payout is rejected.

Available options:
standard,
instant
Example:

"standard"

user_id
string

User to pay out from, prefixed user_. Provide exactly one of account_id or user_id.

Example:

"user_xxxxxxxxxxxxxx"

Response

payout created

amount
string<decimal>
required

The payout amount in whole currency units, as a decimal string.

Example:

"50.0"

created_at
string<date-time>
required

When the payout was created.

Example:

"2026-01-01T12:00:00.000Z"

currency
string
required

Payout currency.

Example:

"usd"

destination_amount
string<decimal> | null
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 | null
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> | null
required

Estimated time the funds become available in the destination account. Null until the payout settles.

Example:

"2026-01-01T12:00:00.000Z"

exchange_rate
number<float> | null
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 | null
required

Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; null otherwise.

fee_amount
string<decimal>
required

The fee charged for the payout, in the payout currency, as a decimal string.

Example:

"2.5"

fee_paid_by
enum<string>
required

Who bore the payout fee: the account itself, or its parent platform.

Available options:
self,
platform
Example:

"self"

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.

Example:

"wdrl_xxxxxxxxxxxxx"

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.

Example:

"0.0"

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.

Example:
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.

Example:

"49.75"

notes
string | null
required

Free-form notes attached by the payout creator, or null when none were provided. Maximum 255 characters.

Maximum string length: 255
Example:

"Detailing supplies restock"

object
enum<string>
required
Available options:
payout
Example:

"payout"

payer_name
string | null
required

Name of the entity processing the payout. Null until the payout settles.

Example:

"MassPay"

payout_method
object | null
required

The saved payout method used. Requires payout:destination:read; null without it.

payout_request_id
string | null
required

For a stablecoin payout, the id of the conversion request that funds it, prefixed cofr_; null on fiat payouts.

Example:

"cofr_xxxxxxxxxxxxx"

source
enum<string> | null
required

How the payout was created. automatic means a scheduled auto-payout; null on payouts created before source tracking or through internal tooling.

Available options:
api,
dashboard,
automatic,
null
Example:

"api"

speed
enum<string>
required

Payout delivery speed.

Available options:
standard,
instant
Example:

"instant"

status
enum<string>
required

Current payout status, in the same vocabulary as GET /payouts.

Available options:
requested,
in_review,
processing,
completed,
reversed,
canceled,
failed,
denied
Example:

"in_review"

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.

Example:

"pending_debit"

trace_code
string | null
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.