> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Payment Method
> Create a new payment method.
**API scope required**: `payment-methods.create`
**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](/agents/payment-methods/cards/save-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.
## OpenAPI
````yaml post /unstable/payment-methods
openapi: 3.0.1
info:
description: |
Offramp APIs for cashing out stablecoins to fiat.
version: 1.0.0
title: Offramp
contact:
name: Crossmint Offramp APIs
url: https://www.crossmint.com
email: support@crossmint.com
servers:
- url: https://staging.crossmint.com/api
description: Staging environment (testnets)
- url: https://www.crossmint.com/api
description: Production environment (mainnets)
security: []
tags:
- name: Offramp
description: APIs to cash out stablecoins to fiat (offramp)
- name: Payment Methods
description: Manage bank account payout methods for offramp.
paths:
/unstable/payment-methods:
post:
tags:
- Payment Methods
summary: Create a payment method
description: >-
Saves a bank account payout method for a user so offramp orders can
settle to it. Account numbers and IBANs are tokenized by the
PCI-compliant vault before reaching Crossmint servers, so create
requests must be submitted through `vault.crossmint.com`. Duplicate
detection prevents saving the same account twice for the same user.
Supported types are the bank-account variants (`bank-account-us`,
`bank-account-mx-clabe`, `bank-account-co`, `bank-account-sepa-iban`);
the payout currency must match the account geography.
**API scope required**: `payment-methods.create`
operationId: createPaymentMethod
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PmCreatePaymentMethodRequest'
examples:
SEPA:
summary: SEPA
value:
type: bank-account-sepa-iban
userLocator: email:hans.mueller@example.com
bankAccount:
iban: DE89370400440532013000
bic: COBADEFFXXX
billing:
name: Hans Müller
currency: eur
country: DE
entityType: individual
BankAccountUs:
summary: US Bank Account
value:
type: bank-account-us
userLocator: email:alice@example.com
bankAccount:
accountNumber: '5071056259'
routingNumber: '091300010'
accountType: checking
currency: usd
country: US
entityType: individual
bankName: Chime
billing:
name: Alice Smith
phone: '+12125551234'
address:
line1: 123 Main St
city: New York
postalCode: '10001'
country: US
stateOrRegion: NY
bankAddress:
line1: 123 Main St
city: New York
stateOrRegion: NY
postalCode: '10001'
country: US
BankAccountMx:
summary: MX Bank Account (business)
value:
type: bank-account-mx-clabe
userLocator: email:empresa@example.mx
bankAccount:
accountNumber: '032180000118359719'
currency: mxn
country: MX
entityType: business
taxId: CAZ920101ABC
businessDescription: Retail goods importer
billing:
name: Comercializadora Azteca SA de CV
phone: '+525512345678'
address:
line1: Av. Reforma 1
city: Mexico City
postalCode: '06600'
country: MX
stateOrRegion: CDMX
BankAccountCo:
summary: CO Bank Account
value:
type: bank-account-co
userLocator: email:carlos.gomez@example.com
bankAccount:
accountNumber: '1234567890'
bankCode: '001'
accountType: savings
documentType: CC
documentNumber: '1234567890'
billing:
name: Carlos Gómez
phone: '+573001234567'
address:
line1: Carrera 7
city: Bogotá
stateOrRegion: DC
postalCode: '110010'
country: CO
currency: cop
country: CO
entityType: individual
responses:
'201':
description: >-
Payment method created successfully. Returns the full PaymentMethod
object including the derived `displayName` and the `bankAccount`
sub-object.
content:
application/json:
schema:
$ref: '#/components/schemas/PmPaymentMethod'
examples:
SEPA:
summary: SEPA
value:
paymentMethodId: 3323460b-d9d2-4ec6-b380-8a3e01e3f226
default: false
displayName: SEPA Account ••6789
type: bank-account-sepa-iban
bankAccount:
billing:
name: Hans Müller
phone: '+4915112345678'
address:
line1: Unter den Linden 1
city: Berlin
stateOrRegion: BE
postalCode: '10117'
country: DE
bankName: null
accountSuffix: '6789'
currency: eur
country: DE
entityType: individual
bic: COBADEFFXXX
BankAccountUs:
summary: US Bank Account
value:
paymentMethodId: dd8a59c6-aac0-47c2-9c21-686caf7f0359
default: false
displayName: Chime ••6259
type: bank-account-us
bankAccount:
billing:
name: Alice Smith
phone: '+12125551234'
address:
line1: 123 Main St
city: New York
stateOrRegion: NY
postalCode: '10001'
country: US
bankName: Chime
accountSuffix: '6259'
currency: usd
country: US
entityType: individual
bankAddress:
line1: 123 Main St
city: New York
stateOrRegion: NY
postalCode: '10001'
country: US
routingNumber: '091300010'
accountType: checking
BankAccountMx:
summary: MX Bank Account
value:
paymentMethodId: 27bacbe1-d0ff-4bc3-b37a-ca91cc64fa39
default: false
displayName: MX Bank Account ••9719
type: bank-account-mx-clabe
bankAccount:
billing:
name: Javier Toledo
phone: '+525512345678'
address:
line1: Av. Reforma 1
city: Mexico City
stateOrRegion: CDMX
postalCode: '06600'
country: MX
bankName: null
accountSuffix: '9719'
currency: mxn
country: MX
entityType: individual
bankCode: '138'
BankAccountCo:
summary: CO Bank Account
value:
paymentMethodId: 1cad2281-bd3d-4219-8787-7dfea94c60b1
default: false
displayName: CO Bank Account ••7890
type: bank-account-co
bankAccount:
billing:
name: Carlos Gómez
phone: '+573001234567'
address:
line1: Carrera 7
city: Bogotá
stateOrRegion: DC
postalCode: '110010'
country: CO
bankName: null
accountSuffix: '7890'
currency: cop
country: CO
entityType: individual
bankCode: '001'
accountType: savings
'400':
description: Request validation failed or duplicate payment method.
content:
application/json:
schema:
$ref: '#/components/schemas/Pm400ResponseCreate'
examples:
duplicate:
description: Duplicate payment method
value:
error: true
message: >-
Payment method already exists for this user with the same
details
sepa_business:
description: SEPA business not supported
value:
error: true
message: SEPA business accounts are not supported
sensitive_data:
description: >-
Sensitive data sent directly to www.crossmint.com instead of
vault.crossmint.com
value:
error: true
message: >-
Payment method requests must be submitted through
vault.crossmint.com. Sensitive data cannot be sent
directly to api.crossmint.com.
code: PAYMENT_METHOD_SENSITIVE_DATA_NOT_ALLOWED
missing_locator:
description: Missing userLocator when using API key auth
value:
error: true
message: userLocator is required when not using JWT authentication
code: PAYMENT_METHOD_INVALID_USER_LOCATOR
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Pm401Response'
'403':
description: Authentication source not allowed or required add-on not enabled.
content:
application/json:
schema:
$ref: '#/components/schemas/Pm403Response'
examples:
auth_source:
description: Authentication source not allowed
value:
error: true
message: >-
Payment methods are not allowed with this authentication
source
'422':
description: Request body failed schema validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Pm422Response'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Pm429Response'
security:
- apiKey: []
servers:
- url: https://vault.staging.crossmint.com/api
description: Staging (PCI vault)
- url: https://vault.crossmint.com/api
description: Production (PCI vault)
components:
schemas:
PmCreatePaymentMethodRequest:
type: object
description: >-
Create request for a bank account payout method. Provide the
`bankAccount` sub-object with the fields required by the chosen `type`.
required:
- type
properties:
type:
type: string
enum:
- bank-account-us
- bank-account-mx-clabe
- bank-account-co
- bank-account-sepa-iban
description: >-
Payout method type. Determines the country-specific `bankAccount`
fields that must be provided.
userLocator:
type: string
description: >-
Identifies the target user. Format: `:` (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).
bankAccount:
type: object
description: >-
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.
properties:
accountNumber:
type: string
description: >-
Bank account number. For US: 4-17 digits. For MX: 18-digit
CLABE. For CO: account number. Tokenized by the vault — never
stored in plaintext.
routingNumber:
type: string
description: >-
Nine-digit ABA routing transit number with checksum validation.
US bank accounts only.
iban:
type: string
description: >-
IBAN (ISO 13616, 15-34 characters). Tokenized by the vault —
never stored in plaintext. SEPA only.
bic:
type: string
description: >-
BIC/SWIFT code (ISO 9362, 8 or 11 uppercase alphanumeric
characters). Optional — under EPC IBAN-only rules, the BIC can
be derived from the IBAN. SEPA only.
bankName:
type: string
description: >-
Name of the bank (e.g., "Wells Fargo", "Deutsche Bank").
Required for US; optional for SEPA.
bankAddress:
type: object
description: Bank branch mailing address. US bank accounts only.
bankCode:
type: string
description: >-
Bank code. For MX: 3-digit code from the CLABE. For CO: code
assigned by Banco de la República.
accountType:
type: string
enum:
- checking
- savings
description: >-
Account type: `checking` or `savings`. Required for US and CO
bank accounts.
documentType:
type: string
description: >-
Colombian document type: `CC` (Cédula), `NIT` (Tax ID), `CE`
(Cédula de Extranjería), `PASS` (Passport), or `PEP` (Special
Permit). CO only.
documentNumber:
type: string
description: >-
Document number matching `documentType`. Tokenized by the vault.
CO only.
billing:
type: object
description: Account holder billing details. `name` is always required.
properties:
name:
type: string
description: Account holder full legal name.
phone:
type: string
description: Phone number in E.164 format (e.g., `+4915112345678`).
address:
type: object
description: >-
Billing address. When provided, `line1`, `city`,
`postalCode`, and `country` are required.
properties:
line1:
type: string
description: Primary address line (max 200 characters).
line2:
type: string
description: >-
Secondary address line — apartment, suite, unit, etc.
(max 60 characters).
city:
type: string
description: City (max 50 characters).
stateOrRegion:
type: string
description: >-
State, province, or region (max 50 characters). Required
for all types except SEPA.
postalCode:
type: string
description: Postal or ZIP code (max 20 characters).
country:
type: string
description: >-
Two-letter ISO 3166-1 alpha-2 country code (e.g., `US`,
`DE`).
required:
- line1
- city
- postalCode
- country
required:
- name
currency:
type: string
description: >-
ISO 4217 currency code in lowercase. Must match the type: `usd`
for US, `mxn` for MX, `cop` for CO, `eur` for SEPA.
country:
type: string
description: >-
ISO 3166-1 alpha-2 country code. For SEPA, must be one of the 37
EPC member states or Gibraltar.
entityType:
type: string
enum:
- individual
- business
description: >-
Account holder type: `individual` or `business`. SEPA does not
currently support `business`.
required:
- billing
- currency
- country
- entityType
PmPaymentMethod:
title: Bank account
type: object
description: >-
A saved bank account payout method. Sensitive fields (full account
numbers and IBANs) are never included in responses.
properties:
paymentMethodId:
type: string
format: uuid
description: Unique identifier (UUID v4), assigned by the server on creation.
default:
type: boolean
description: >-
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:
type: string
description: >-
Human-readable label derived by the server (e.g., "Chime ••6259",
"SEPA Account ••6789"). Not settable by the client.
type:
type: string
enum:
- bank-account-us
- bank-account-mx-clabe
- bank-account-co
- bank-account-sepa-iban
description: >-
Payout method type. Determines the country-specific `bankAccount`
fields that are present.
bankAccount:
type: object
description: >-
Bank account details. Present when `type` is a bank type. Full
account numbers and IBANs are never included.
properties:
billing:
type: object
description: Account holder billing details as provided on creation.
bankName:
type: string
description: Name of the bank, or `null` if the bank could not be identified.
nullable: true
accountSuffix:
type: string
description: Last four digits of the account number, CLABE, or IBAN.
currency:
type: string
description: ISO 4217 currency code in lowercase (e.g., `usd`, `eur`).
country:
type: string
description: ISO 3166-1 alpha-2 country code.
entityType:
type: string
description: Account holder type. Present when provided on creation.
enum:
- individual
- business
routingNumber:
type: string
description: ABA routing number. US only.
accountType:
type: string
description: Account type. US and CO only.
enum:
- checking
- savings
bankAddress:
type: object
description: Bank mailing address. US only.
bankCode:
type: string
description: Bank code. MX and CO only.
bic:
type: string
description: BIC/SWIFT code. SEPA only; present when provided on creation.
taxId:
type: string
description: Mexican tax identifier (RFC). MX only; present when provided.
businessDescription:
type: string
description: Business description. MX only; present when provided.
required:
- billing
- bankName
- accountSuffix
- currency
- country
lastPayoutAt:
type: string
format: date-time
description: >-
Read-only. ISO 8601 timestamp of the most recent successful offramp
payout funded by this bank account. Absent if none.
required:
- paymentMethodId
- default
- type
- displayName
- bankAccount
Pm400ResponseCreate:
type: object
properties:
error:
type: boolean
example: true
message:
type: string
description: Human-readable error message describing what went wrong
code:
type: string
description: Machine-readable error code for programmatic handling
enum:
- PAYMENT_METHOD_SENSITIVE_DATA_NOT_ALLOWED
- PAYMENT_METHOD_INVALID_USER_LOCATOR
- PAYMENT_METHOD_PROXY_FIELDS_MISSING
description: Bad request on payment method creation.
Pm401Response:
type: object
properties:
error:
type: boolean
example: true
message:
type: string
example: Missing or invalid API key.
description: Missing or invalid API key / JWT.
Pm403Response:
type: object
properties:
error:
type: boolean
example: true
message:
type: string
example: Payment methods are not allowed with this authentication source
description: API key lacks the required scope for this operation.
Pm422Response:
type: object
properties:
error:
type: boolean
example: true
message:
type: string
example: Request body failed schema validation
description: >-
Request body validation failed (e.g., missing required fields, invalid
field format).
Pm429Response:
type: object
properties:
error:
type: boolean
example: true
message:
type: string
example: Rate limit exceeded
description: >-
Rate limit exceeded. Retry after the interval indicated in the
Retry-After header.
securitySchemes:
apiKey:
type: apiKey
name: X-API-KEY
in: header
````