Skip to main content
POST
Saves a bank account payout method for a user so offramp orders can settle to it.
Account numbers and IBANs are tokenized by the PCI-compliant vault, so create requests must be submitted through vault.crossmint.com.

​
Returns

Returns a PaymentMethod object.

Authorizations

​
X-API-KEY
string
header
required

Body

application/json

Create request for a bank account payout method. Provide the bankAccount sub-object with the fields required by the chosen type.

​
type
enum<string>
required

Payout method type. Determines the country-specific bankAccount fields that must be provided.

Available options:
bank-account-us
​
bankAccount
object
required

Bank account details. Required when type is a bank type. The exact fields depend on the country-specific type. Account numbers and IBANs are tokenized by the vault.

​
userLocator
string

Identifies the target user. Format: <type>:<value> (e.g., email:alice@example.com, userId:abc123). Required when authenticating with a server API key; ignored with JWT (the JWT subject is used instead).

​
label
string

The client's own name for this payment method. Free text, at most 255 characters, echoed back on every read.

Required string length: 1 - 255

Response

Payment method created successfully. Returns the full PaymentMethod object including the derived displayName and the bankAccount sub-object.

A saved bank account payout method. Sensitive fields (full account numbers and IBANs) are never included in responses.

​
paymentMethodId
string<uuid>
required

Unique identifier (UUID v4), assigned by the server on creation.

​
type
enum<string>
required

Payout method type. Determines the country-specific bankAccount fields that are present.

Available options:
bank-account-us,
bank-account-mx-clabe,
bank-account-co
​
status
enum<string>
required

Whether this destination can receive a payout right now. 'active' when a provider has confirmed a rail, 'pending' while rail resolution is still running, 'rejected' when it cannot receive funds, 'deleted' when it was deleted. 'deleted' is terminal and carries no reason. Branch on this field, never on reason.

Available options:
active,
deleted,
pending,
rejected
​
reason
string | null
required

Why the status is not 'active'. Null when it is, and on a 'pending' status other than a provider outage. Known values today: provider-unavailable, destination-not-found, destination-closed, destination-cannot-receive, no-rail-available, deleted, disabled. New codes can appear at any time, so branch on status and treat an unrecognised reason as the status alone.

​
bankAccount
object
required

Bank account details. Present when type is a bank type. Full account numbers and IBANs are never included.

​
label
string

The client's own name for this payment method, when one was sent on creation.

​
lastPayoutAt
string<date-time>

Read-only. ISO 8601 timestamp of the most recent successful offramp payout funded by this bank account. Absent if none.