Skip to main content
PATCH
/
unstable
/
payment-methods
/
{paymentMethodId}
Update a payment method
curl --request PATCH \
  --url https://www.crossmint.com/api/unstable/payment-methods/{paymentMethodId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "billingDetails": {
    "address": {
      "line1": "456 Oak Ave",
      "city": "Chicago",
      "postalCode": "60601",
      "country": "US",
      "stateOrRegion": "IL"
    }
  }
}
'
{
  "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"
  }
}
Updates a payment method’s billing details or default status. Only default and billingDetails can be changed.

​
Returns

Returns the updated PaymentMethod object.

Authorizations

​
X-API-KEY
string
header
required

Server-side API key from the Crossmint dashboard.

Path Parameters

​
paymentMethodId
string<uuid>
required

PaymentMethod identifier.

Query Parameters

​
userLocator
string

Identifies the target user. Format: <type>:<value> (e.g., email:alice@example.com, userId:abc123). Required with server API key auth; ignored with JWT.

Body

application/json

At least one of default or billingDetails must be provided. Payment type, card details, and account numbers cannot be changed after creation.

​
default
boolean

Set to true to make this the user's default payment method. Automatically unsets the previous default.

​
billingDetails
object

Updated billing information. Must include at least one of name, phone, or address. Only provided fields are updated; omitted fields remain unchanged.

Response

Updated PaymentMethod object.

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.