---
title: "Update a payment method"
method: PATCH
path: "/unstable/payment-methods/{paymentMethodId}"
tags: ["Payment Methods"]
---

# Update a payment method

`PATCH /unstable/payment-methods/{paymentMethodId}`

Updates a payout method's billing details or default status. Only `default` and `billingDetails` can be modified; the account type and account numbers are immutable after creation. The request body must contain at least one of these fields.

**API scope required**: `payment-methods.update`

## Path parameters

- `paymentMethodId` string, uuid, required

## Query parameters

- `userLocator` string

## Request body

- PmUpdatePaymentMethodRequest — At least one of `default` or `billingDetails` must be provided. Payout method type 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.
    - `name` string — Updated full name.
    - `phone` string — Updated phone number in E.164 format.
    - `address` object — Updated billing address. Replaces the entire address object. All fields except `line2` are required.
      - `line1` string, required — Primary address line (max 200 characters).
      - `line2` string — Secondary address line — apartment, suite, unit, etc. (max 60 characters).
      - `city` string, required — City (max 50 characters).
      - `stateOrRegion` string, required — State, province, or region (max 50 characters).
      - `postalCode` string, required — Postal or ZIP code (max 20 characters).
      - `country` string, required — Two-letter ISO 3166-1 alpha-2 country code (e.g., `US`, `DE`).

## Response `200`

Updated PaymentMethod object.

- PmPaymentMethod — A saved bank account payout method. Sensitive fields (full account numbers and IBANs) 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., "Chime ••6259", "SEPA Account ••6789"). Not settable by the client.
  - `type` 'bank-account-us' | 'bank-account-mx-clabe' | 'bank-account-co' | 'bank-account-sepa-iban', required — Payout method type. Determines the country-specific `bankAccount` fields that are present.
  - `bankAccount` object, required — Bank account details. Present when `type` is a bank type. Full account numbers and IBANs are never included.
    - `billing` object, required — Account holder billing details as provided on creation.
    - `bankName` string, nullable, required — Name of the bank, or `null` if the bank could not be identified.
    - `accountSuffix` string, required — Last four digits of the account number, CLABE, or IBAN.
    - `currency` string, required — ISO 4217 currency code in lowercase (e.g., `usd`, `eur`).
    - `country` string, required — ISO 3166-1 alpha-2 country code.
    - `entityType` 'individual' | 'business' — Account holder type. Present when provided on creation.
    - `routingNumber` string — ABA routing number. US only.
    - `accountType` 'checking' | 'savings' — Account type. US and CO only.
    - `bankAddress` object — Bank mailing address. US only.
    - `bankCode` string — Bank code. MX and CO only.
    - `bic` string — BIC/SWIFT code. SEPA only; present when provided on creation.
    - `taxId` string — Mexican tax identifier (RFC). MX only; present when provided.
    - `businessDescription` string — Business description. MX only; present when provided.
  - `lastPayoutAt` string, date-time — Read-only. ISO 8601 timestamp of the most recent successful offramp payout funded by this bank account. Absent if none.

## Other responses

- `400` — Invalid request.
- `401` — Missing or invalid API key.
- `403` — Authentication source not allowed.
- `404` — Payment method not found or does not belong to this user.
- `422` — Request body failed schema validation.

---

[API](https://skmtc.net/crossmint/apis/onramp.md) · [All operations](https://skmtc.net/crossmint/apis/onramp/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/crossmint/onramp/revisions/e2143d192130/schema)