Create Payment Method

curl --request POST \
  --url https://vault.crossmint.com/api/unstable/payment-methods \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "type": "card",
  "userLocator": "email:alice@example.com",
  "card": {
    "number": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2028,
    "cvc": "123",
    "billing": {
      "name": "Alice Smith",
      "phone": "+12125551234",
      "address": {
        "line1": "123 Main St",
        "city": "Springfield",
        "stateOrRegion": "IL",
        "postalCode": "62701",
        "country": "US"
      }
    }
  }
}
'

{
  "paymentMethodId": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "default": true,
  "displayName": "Visa ••1111",
  "type": "card",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "expiration": {
      "month": "12",
      "year": "2028"
    },
    "billing": {
      "name": "Alice Smith",
      "phone": "+12125551234",
      "address": {
        "line1": "123 Main St",
        "city": "Springfield",
        "stateOrRegion": "IL",
        "postalCode": "62701",
        "country": "US"
      }
    },
    "fundingType": "debit",
    "bin": "411111",
    "country": "US"
  }
}

POST

unstable

payment-methods

curl --request POST \
  --url https://vault.crossmint.com/api/unstable/payment-methods \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "type": "card",
  "userLocator": "email:alice@example.com",
  "card": {
    "number": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2028,
    "cvc": "123",
    "billing": {
      "name": "Alice Smith",
      "phone": "+12125551234",
      "address": {
        "line1": "123 Main St",
        "city": "Springfield",
        "stateOrRegion": "IL",
        "postalCode": "62701",
        "country": "US"
      }
    }
  }
}
'

{
  "paymentMethodId": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "default": true,
  "displayName": "Visa ••1111",
  "type": "card",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "expiration": {
      "month": "12",
      "year": "2028"
    },
    "billing": {
      "name": "Alice Smith",
      "phone": "+12125551234",
      "address": {
        "line1": "123 Main St",
        "city": "Springfield",
        "stateOrRegion": "IL",
        "postalCode": "62701",
        "country": "US"
      }
    },
    "fundingType": "debit",
    "bin": "411111",
    "country": "US"
  }
}

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

Server-side API key from the Crossmint dashboard.

Body

application/json

Create request. Provide the sub-object that matches the chosen type.

type

enum<string>

required

Payment method type. Determines which sub-object (card or bankAccount) must be provided.

Available options:

card,

bank-account-us,

bank-account-mx-clabe,

bank-account-co,

bank-account-sepa-iban

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

card

object

Card details. Required when type is card. All card data is tokenized by the PCI vault before it reaches Crossmint servers.

Show child attributes

bankAccount

object

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.

Show child attributes

Response

Payment method created successfully. Returns the full PaymentMethod object including the derived displayName and the type-specific sub-object (card or bankAccount).

Bank account
Card

A saved payment method. Sensitive fields (full PAN, CVC, full account numbers) are never included in responses.

paymentMethodId

string<uuid>

required

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

default

boolean

required

Whether this is the user's default payment method. Only one per user can be the default; setting a new default automatically unsets the previous one.

displayName

string

required

Human-readable label derived by the server (e.g., "Visa ••1111", "SEPA Account ••6789"). Not settable by the client.

type

enum<string>

required

Payment method type. Determines which sub-object (card or bankAccount) is present.

Available options:

bank-account-us,

bank-account-mx-clabe,

bank-account-co,

bank-account-sepa-iban

bankAccount

object

required

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

Show child attributes

lastPayoutAt

string<date-time>

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

Delete Agent List Payment Methods

⌘I

Agents

Quickstarts ⚡

Payment Methods

Payment Flows

API Reference

Authorizations

Body

Response