> ## 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.
# Delete Payment Method
> Delete a payment method.
**API scope required**: `payment-methods.delete`
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 delete /unstable/payment-methods/{paymentMethodId}
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/{paymentMethodId}:
parameters:
- $ref: '#/components/parameters/PaymentMethodId'
delete:
tags:
- Payment Methods
summary: Delete a payment method
description: >-
Soft-deletes a payment method. The record is retained for compliance but
is excluded from list and retrieve operations and can no longer be used
for payments. Returns the payment method as it existed before deletion.
operationId: deletePaymentMethod
parameters:
- name: paymentMethodId
in: path
required: true
schema:
type: string
format: uuid
description: UUID of the payment method.
- 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
responses:
'200':
description: >-
PaymentMethod object (pre-deletion state). The record is no longer
returned by list or retrieve endpoints.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod'
examples:
Card:
summary: Card
value:
paymentMethodId: d4e5f6a7-b8c9-0123-def4-567890abcdef
default: false
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
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: Invalid request.
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: Payment method not found or does not belong to this user.
content:
application/json:
schema:
$ref: '#/components/schemas/404Response'
servers:
- url: https://www.crossmint.com/api
description: Production
- url: https://staging.crossmint.com/api
description: Staging
components:
parameters:
PaymentMethodId:
name: paymentMethodId
in: path
required: true
schema:
type: string
format: uuid
description: PaymentMethod identifier.
schemas:
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
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.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: Server-side API key from the Crossmint dashboard.
````