> ## 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.
# List Payment Methods
> List all payment methods for the authenticated user.
**API scope required**: `payment-methods.read`
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.
## OpenAPI
````yaml get /unstable/payment-methods
openapi: 3.0.3
info:
title: Crossmint Payment Methods API
version: unstable
description: >-
Manage payment methods for Crossmint users. Use these endpoints to create,
retrieve, update, delete, and list saved payment instruments.
## Base URLs
| Operation | Base URL |
|---|---|
| Create (POST) | `https://vault.crossmint.com/api` |
| All other operations | `https://www.crossmint.com/api` |
The create endpoint routes through a PCI-compliant proxy that tokenizes
sensitive payment data before it reaches Crossmint servers.
## Authentication
All requests require a server-side API key in the `X-API-KEY` header.
servers:
- url: https://www.crossmint.com/api
description: Production
- url: https://staging.crossmint.com/api
description: Staging
security:
- ApiKeyAuth: []
tags:
- name: Payment Methods
description: Create, retrieve, update, delete, and list payment methods.
paths:
/unstable/payment-methods:
get:
tags:
- Payment Methods
summary: List payment methods by user
description: >-
Returns a paginated list of payment methods for a user. Soft-deleted
methods are excluded. Results are ordered by creation date (newest first
by default).
operationId: listPaymentMethodsByUser
parameters:
- name: userLocator
in: query
required: false
schema:
type: string
description: >-
Identifies the target user. Format: `:` (e.g.,
`email:alice@example.com`, `userId:abc123`). Required with server
API key auth; ignored with JWT.
example: email:alice@example.com
- name: type
in: query
required: false
schema:
type: string
enum:
- card
- bank-account-us
- bank-account-mx-clabe
- bank-account-co
- bank-account-sepa-iban
description: >-
Filter by payment method type. Without this filter, all types are
returned.
- name: cursor
in: query
required: false
schema:
type: string
description: >-
Opaque pagination cursor from a previous response. Pass to retrieve
the next page.
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 30
description: Maximum number of results per page (1-100, default 30).
- name: sort
in: query
required: false
schema:
type: string
enum:
- asc
- desc
description: >-
Sort by creation date: `asc` (oldest first) or `desc` (newest first,
default).
- name: hasPayout
in: query
required: false
schema:
type: string
enum:
- 'true'
- 'false'
description: >-
Filter to payment methods that have (true) or have not (false)
funded a settled offramp payout. When set to false, cards are
included in results. Omit to return all payment methods regardless
of payout history.
responses:
'200':
description: >-
Paginated list of PaymentMethod objects. `nextCursor` and
`previousCursor` are included when additional pages exist in that
direction.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedPaymentMethods'
example:
data:
- 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
- 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
- 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
nextCursor: eyJsYXN0SWQiOiI2NDUifQ==
previousCursor: null
'400':
description: Invalid query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/400ResponseGeneral'
examples:
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/401Response'
'403':
description: Authentication source not allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/403Response'
'404':
description: User not found for the given locator.
content:
application/json:
schema:
$ref: '#/components/schemas/404Response'
examples:
user_not_found:
description: User not found
value:
error: true
message: User not found for the provided locator
servers:
- url: https://www.crossmint.com/api
description: Production
- url: https://staging.crossmint.com/api
description: Staging
components:
schemas:
PaginatedPaymentMethods:
type: object
description: Paginated list of payment methods.
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/PaymentMethod'
description: Array of payment method objects for the current page.
nextCursor:
type: string
nullable: true
description: >-
Cursor to fetch the next page. `null` when there are no more
results.
previousCursor:
type: string
nullable: true
description: Cursor to fetch the previous page. `null` on the first page.
400ResponseGeneral:
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_INVALID_USER_LOCATOR
description: Bad request (e.g., missing or invalid userLocator).
401Response:
type: object
properties:
error:
type: boolean
example: true
message:
type: string
example: Missing or invalid API key.
description: Missing or invalid API key / JWT.
403Response:
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.
404Response:
type: object
properties:
error:
type: boolean
example: true
message:
type: string
example: Payment method not found
description: Payment method not found, deleted, or belongs to a different user.
PaymentMethod:
description: >-
A saved payment method. Sensitive fields (full PAN, CVC, full account
numbers) are never included in responses.
oneOf:
- type: object
description: >-
A saved payment method. Sensitive fields (full PAN, CVC, full
account numbers) 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., "Visa ••1111",
"SEPA Account ••6789"). Not settable by the client.
type:
type: string
enum:
- card
description: >-
Payment method type. Determines which sub-object (`card` or
`bankAccount`) is present.
card:
type: object
description: Card details. Present when `type` is `card`.
properties:
brand:
type: string
description: Card network brand, detected from the card number.
enum:
- visa
- mastercard
- amex
- discover
- jcb
- unionpay
- diners-club
last4:
type: string
description: Last four digits of the card number.
expiration:
type: object
description: Card expiration date.
properties:
month:
type: string
description: Two-digit month, zero-padded (`01`-`12`).
year:
type: string
description: Four-digit year.
required:
- month
- year
billing:
type: object
description: Cardholder billing details as provided on creation.
properties:
name:
type: string
description: Cardholder name.
phone:
type: string
description: Phone number.
address:
type: object
description: Billing address.
required:
- name
fundingType:
type: string
description: >-
Card funding type, detected from the BIN. Present when the
issuer provides this data.
enum:
- credit
- debit
- prepaid
- unknown
bin:
type: string
description: >-
Bank Identification Number (first 6-8 digits). Present when
available from the card network.
country:
type: string
description: >-
ISO 3166-1 alpha-2 code of the card-issuing country. Present
when available from the card network.
required:
- brand
- last4
- expiration
- billing
required:
- paymentMethodId
- default
- type
- displayName
- card
- type: object
description: >-
A saved payment method. Sensitive fields (full PAN, CVC, full
account numbers) 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., "Visa ••1111",
"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: >-
Payment method type. Determines which sub-object (`card` or
`bankAccount`) is 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
availableTiers:
type: array
description: >-
Offramp speed tiers serviceable for this account, each with
backing rail(s). Empty if none.
items:
type: object
properties:
tier:
type: string
enum:
- instant
- same_day
- multi_day
rails:
type: array
items:
type: string
enum:
- wire
- ach_credit
- same_day_ach_credit
- rtp_credit
- sepa
- sepa_instant
- faster_payments
- swift
- spei
- pse
- fednow
- chaps
required:
- tier
- rails
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
- availableTiers
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: Server-side API key from the Crossmint dashboard.
````