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"
  }
}
Saves a payment method for a user so it can be reused across Checkout, Onramp, and Offramp orders.
Card payments require PCI-DSS certification for production access. Contact your Crossmint customer success engineer to get started. Bank account and SEPA payment methods do not have this requirement.

​
Returns

Returns a PaymentMethod object.

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.