Skip to main content
POST
Create Payout
This endpoint requires an Idempotency-Key header to prevent duplicate payouts.

Path Parameters

string
required
The account’s external ID (starts with acct_)

Headers

string
required
Unique key to prevent duplicate payouts (e.g., UUID v4)

Request Body

string
required
Beneficiary external ID (starts with bene_)
string
required
Payout destination external ID (starts with dest_)
string
required
Payout amount (decimal string, must be positive)
string
required
ISO 4217 currency code
string
Optional internal note (max 500 characters)
object
Fee the platform charges its end user, debited from the funding source on top of amount and credited to the platform’s fee-collection account when the payout completes. Released back if the payout fails or is cancelled; not refunded on a return. Platform customers only (end-customer accounts, feature-flagged); currency must equal the payout currency. Fields: currency (string) and amount (string, > 0, at most the currency’s decimal places).

Response

string
Payout identifier (starts with po_)
string
Always returns "payout"
string
Account ID
string
Beneficiary ID
string
Payout destination ID
string
Payout amount (decimal)
string
Currency code
string
Amount converted to USD
object
Platform fee charged on top of amount (currency, amount), or null when none.
string
Payout status: pending_approval, pending, processing, completed, or failed
string
Payment provider (null until submitted)
string
Provider reference ID
string
ISO 8601 timestamp when payout was initiated
string
ISO 8601 timestamp when payout was submitted to provider
string
ISO 8601 timestamp when payout completed
string
ISO 8601 timestamp when payout failed
string
Reason for failure
string
Optional note
string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated

Response Example