> ## 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
> Save a bank account payout method so offramp orders can settle fiat to it.
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, so create requests must be submitted through `vault.crossmint.com`.
## Returns
Returns a [PaymentMethod](/offramp/api-reference/payment-methods/payment-method-object) object.
## OpenAPI
````yaml api-reference/_open-api/OfframpAPIs.json 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
````