Skip to main content
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 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,
bank-account-co,
sepa
​
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.

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

Response

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

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:
card,
bank-account-us,
bank-account-mx,
bank-account-co,
sepa
​
card
object

Card details. Present when type is card.

​
bankAccount
object

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