curl --request POST \
  --url https://vault.staging.crossmint.com/api/unstable/payment-methods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "bankAccount": {
    "accountNumber": "1234567890",
    "accountType": "savings",
    "bankCode": "001",
    "billing": {
      "address": {
        "city": "Bogotá",
        "country": "CO",
        "line1": "Carrera 7",
        "postalCode": "110010",
        "stateOrRegion": "DC"
      },
      "name": "Carlos Gómez",
      "phone": "+573001234567"
    },
    "country": "CO",
    "currency": "cop",
    "documentNumber": "1234567890",
    "documentType": "cc",
    "entityType": "individual"
  },
  "type": "bank-account-co",
  "userLocator": "email:carlos.gomez@example.com"
}
'

{
  "bankAccount": {
    "accountSuffix": "7890",
    "accountType": "savings",
    "bankCode": "001",
    "bankName": null,
    "country": "CO",
    "currency": "cop",
    "entityType": "individual"
  },
  "createdAt": "2026-08-20T19:10:00.000Z",
  "paymentMethodId": "1cad2281-bd3d-4219-8787-7dfea94c60b1",
  "reason": null,
  "status": "pending",
  "statusReason": null,
  "type": "bank-account-co",
  "updatedAt": "2026-08-20T19:12:11.000Z"
}

Payment Methods

Create Payment Method

Saves a payment method for a user so it can be reused across Checkout, Onramp, and Offramp orders. Sensitive fields (PAN, CVC, account numbers, IBANs, Bre-B keys) must be submitted through vault.crossmint.com, which tokenizes them before forwarding to Crossmint servers. Duplicate detection prevents saving the same card or account twice for the same user.

Supported types are card, the bank-account variants (bank-account-us, bank-account-mx-clabe, bank-account-co, bank-account-sepa-iban, bank-account-ph) and bre-b. For bank accounts the currency must match the account geography.

API scope required: payment-methods.create

POST

unstable

payment-methods

curl --request POST \
  --url https://vault.staging.crossmint.com/api/unstable/payment-methods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "bankAccount": {
    "accountNumber": "1234567890",
    "accountType": "savings",
    "bankCode": "001",
    "billing": {
      "address": {
        "city": "Bogotá",
        "country": "CO",
        "line1": "Carrera 7",
        "postalCode": "110010",
        "stateOrRegion": "DC"
      },
      "name": "Carlos Gómez",
      "phone": "+573001234567"
    },
    "country": "CO",
    "currency": "cop",
    "documentNumber": "1234567890",
    "documentType": "cc",
    "entityType": "individual"
  },
  "type": "bank-account-co",
  "userLocator": "email:carlos.gomez@example.com"
}
'

{
  "bankAccount": {
    "accountSuffix": "7890",
    "accountType": "savings",
    "bankCode": "001",
    "bankName": null,
    "country": "CO",
    "currency": "cop",
    "entityType": "individual"
  },
  "createdAt": "2026-08-20T19:10:00.000Z",
  "paymentMethodId": "1cad2281-bd3d-4219-8787-7dfea94c60b1",
  "reason": null,
  "status": "pending",
  "statusReason": null,
  "type": "bank-account-co",
  "updatedAt": "2026-08-20T19:12:11.000Z"
}

This endpoint is gated behind Payment Card Industry Data Security Standard (PCI DSS) compliance. Because it accepts raw card numbers, Card Verification Codes (CVCs), and bank account details, you may only use it if your organization is PCI DSS compliant and has been explicitly enabled by Crossmint. You must provide evidence of your compliance (e.g. your Attestation of Compliance) and reach out to Crossmint to have it turned on — it is disabled by default.If you are not PCI compliant, do not use this endpoint. Instead, use the client-side Save a Card flow, which renders Crossmint’s CrossmintPaymentMethodManagement component. Card data is collected directly by Crossmint in the browser and never touches your servers, so you do not need to be PCI compliant to use it.

This endpoint requires a JWT from an external auth provider (Auth0, Firebase, Stytch, etc.) or a custom JWT backed by a JWKS endpoint. Crossmint Auth is not supported.

This endpoint accepts raw card data and bank account details. Requests must be sent to the vault host (vault.staging.crossmint.com or vault.crossmint.com), which tokenizes sensitive fields before forwarding to the API. Raw card numbers, CVCs, and bank account numbers never reach api.crossmint.com directly.

Authorizations

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

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:alice@example.com, userId:abc123, phoneNumber:+12125551234, twitter:alice). Required for API-key authentication; ignored when authenticating with a JWT (the JWT subject is used).

Minimum string length: 1

Response

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

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 this destination can receive a payout right now. 'pending' while the readiness checks run, 'active' when a provider has confirmed a rail, 'rejected' when it cannot receive funds, 'deleted' when it was deleted. '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-mx-clabe"

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"

Introduction

Agent Cards

Agent Wallets

Agent Checkouts

API Reference

Create Payment Method

Authorizations

Body

Response