Create Payment Method

Save a bank account payout method so offramp orders can settle fiat to it.

POST /2026-09-16/payment-methods

cURL

BankAccountAe

curl --request POST \
  --url https://vault.staging.crossmint.com/api/2026-09-16/payment-methods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "bankAccount": {
    "accountHolder": {
      "address": {
        "city": "Dubai",
        "line1": "Sheikh Zayed Road 1"
      },
      "name": "Omar Haddad"
    },
    "entityType": "individual",
    "iban": "AE460090000000123456789"
  },
  "type": "bank-account-ae",
  "userLocator": "email:[e-mail]"
}
'

201

BankAccountAe

{
  "bankAccount": {
    "accountHolder": {
      "address": {
        "city": "Dubai",
        "line1": "Sheikh Zayed Road 1"
      },
      "name": "Omar Haddad"
    },
    "accountSuffix": "6789",
    "country": "AE",
    "currency": "aed",
    "entityType": "individual"
  },
  "createdAt": "2026-10-19T09:00:00.000Z",
  "paymentMethodId": "7c1e5a93-2d4b-4f68-a0c9-3b8e6d2f1a47",
  "reason": null,
  "status": "pending",
  "statusReason": null,
  "type": "bank-account-ae",
  "updatedAt": "2026-10-19T09:00:12.000Z"
}

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

apiKey & userJwtapiKey

X-API-KEY · string · header · required

API key required for authentication

Authorization · string · header · required

The end user's JWT, sent as Authorization: Bearer <JWT> together with a client-side API key. Validated against the project's external JWT configuration.

Body

application/json

MX CLABE

VN bank account

NG bank account

PH bank account

TH bank account

ID bank account

AE bank account

US bank account

CO bank account

SEPA IBAN

CO Bre-B key

Card

Send the sub-object that matches type.

bankAccount · object · required

Bank account details. Required when type is a bank type. The fields depend on the country of the account.

Show child attributes

type · string · required

Account identifier type: Mexican bank account identified by an 18-digit CLABE. type names the account identifier / capture schema Crossmint collects — never the payment rail; rail selection happens at payment execution time.

Allowed value: "bank-account-mx-clabe"

label · string

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

Required string length: 1 - 255

userLocator · string

Identifies the target user when authenticating with a server API key. Format: <type>:<value> (e.g., email:[e-mail], userId:abc123, phoneNumber:[phone], twitter:alice). Required for API-key authentication; ignored when authenticating with a JWT (the JWT subject is used).

Minimum string length: 1

Response

201

application/json

The saved payment method, including the derived displayName and the type-specific sub-object (card, bankAccount, or breB).

CO bank account

MX CLABE

AE bank account

ID bank account

NG bank account

PH bank account

TH bank account

VN bank account

US bank account

SEPA IBAN

CO Bre-B key

Card

A saved payment method. Sensitive fields (full PAN, CVC, full account numbers, IBANs, Bre-B keys) are never included.

bankAccount · object · required

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

Show child attributes

createdAt · string<date-time> · required

ISO 8601 timestamp when this payment method was created.

Example:

"2024-01-15T10:30:00.000Z"

paymentMethodId · string · required

Unique identifier (UUID v4). Crossmint assigns it on creation.

Minimum string length: 1

reason · string | null · required

Deprecated. Use statusReason, which carries the same value.

status · enum<string> · required

Whether a payout provider serves this destination. 'pending' while the readiness checks run, 'active' when a provider advertises a rail for it, 'rejected' when it cannot receive funds, 'deleted' when it was deleted. This describes the destination only, never the payer's eligibility. 'pending' moves to 'active', 'rejected' or 'deleted'; 'active' moves to 'rejected' or 'deleted'; 'rejected' moves only to 'deleted'. Branch on this field, never on statusReason.

Available options: active, deleted, pending, rejected

statusReason · string | null · required

Why the status is 'rejected'. Null on every other status, and on a rejection with no established destination condition. Known values today: destination-not-found, destination-closed, destination-cannot-receive, no-rail-available. New codes can appear at any time, so branch on status and treat an unrecognised code as the status alone.

type · string · required

Payment method type. Selects which sub-object is present: card, bankAccount, or breB.

Allowed value: "bank-account-co"

updatedAt · string<date-time> · required

ISO 8601 timestamp when this payment method was last modified.

Example:

"2024-01-15T10:30:00.000Z"

label · string

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

Minimum string length: 1

lastPayoutAt · string<date-time>

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

Example:

"2024-01-15T10:30:00.000Z"