curl --request POST \
  --url https://vault.staging.crossmint.com/api/unstable/payment-methods \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-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",
  "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) 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 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-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",
  "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.

Headers

X-API-KEY

string

required

API key required for authentication

Body

application/json

bankAccount

object

required

Show child attributes

type

enum<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.

Available options:

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 payment method has been successfully created

bankAccount

object

required

Show child attributes

createdAt

string<date-time>

required

ISO 8601 timestamp when this payment method was created.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

paymentMethodId

string

required

Minimum string length: 1

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. New codes can appear at any time, so branch on status and treat an unrecognised reason as the status alone.

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

type

enum<string>

required

Available options:

bank-account-mx-clabe

updatedAt

string<date-time>

required

ISO 8601 timestamp when this payment method was last modified.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

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.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Agents

Quickstarts ⚡

Payment Methods

Ways to Pay

API Reference

Create Payment Method

Headers

Body

Response