Sign in

v14

latestOpenAPI 3.1.02026-08-083813925.4 MB
Payouts

Create Saved Payout Method

Saves a new place an account or user can withdraw to. Sensitive details are vaulted in transit and never stored raw.

post/payouts/methods

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

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

Request body

account_idstring

The account to add the payout method for (a biz_ identifier). Provide this or user_id.

destination_currencystring

Currency the supported payout method delivers payouts in.

fieldsobject

The supported payout method's required field values, keyed by field id — list them with GET /payouts/supported_methods?supported_payout_method_id=.... A Basis Theory token id may be passed in place of a raw value. A validation failure returns the method's full required_fields schema alongside the error. Required whenever the account details are supplied directly.

is_defaultboolean

Whether to make this the account's default payout method.

nicknamestring

A label for the payout method, unique per destination.

supported_payout_method_idstring required

The supported payout method to save (a podst_ identifier from a previous listing).

user_idstring

The user to add the payout method for (a user_ identifier). Provide this or account_id.

Response

a pre-tokenized Basis Theory value passes through unvaulted

account_referencestring nullable required

Masked identifier for the destination.

bank_verification_state'checking' | 'verified' | 'no_data' | 'warning' | 'broken' | 'null' nullable

Lifecycle trust state: checking (verification still running), verified (bank confirmed ownership or a payout already completed to it), no_data (bank had nothing on file), warning (bank could not confirm ownership), broken (payouts failed with a permanent account error), null (never checked).

created_atstring date-time required
destination_currencystring required
estimated_arrivalobject nullable required

Null on create. List payout methods to retrieve arrival estimates.

fee_structureobject nullable required

Null on create. List payout methods to retrieve the configured fee terms.

idstring required

Payout method ID, usable as payout_method_id on POST /payouts.

institution_namestring nullable required
is_defaultboolean required
nicknamestring nullable required

User-defined label for the payout method.

object'payout_method' required
payer_namestring nullable required
quoteobject nullable required

Always null on create.

status'created' | 'active' | 'broken' required