The Payment Method Object

Attributes and structure of a saved payment method

PaymentMethod objects represent your user’s payment instruments. You can use them with any of the Crossmint products like Checkout, Onramp, and Offramp.

Type Values

type names the account identifier (the capture schema Crossmint collects and validates) — never the payment rail, scheme, or clearing house. The same saved account can be paid over multiple rails; rail selection happens at payment execution time.

Value	Description
card	Credit or debit card.
bank-account-us	US bank account (routing number + account number).
bank-account-mx-clabe	Mexican bank account, identified by an 18-digit CLABE.
bank-account-co	Colombian bank account (bank code + account number + national document).
bank-account-sepa-iban	Bank account identified by an IBAN within the supported SEPA scope.

Attributes

paymentMethodId · string · required

Unique identifier for the payment method.

default · boolean · required

Whether this is the user’s default payment method.

displayName · string · required

Human-readable label for the payment method (e.g. "Visa ••1111", "Chime ••6259").

type · string · required

Payment method type. One of card, bank-account-us, bank-account-mx-clabe, bank-account-co, or bank-account-sepa-iban.

card · object

Card details. Present when type is card.

Show properties

brand · string · required

Card brand. Can be visa, mastercard, amex, discover, jcb, unionpay, or diners-club.

last4 · string · required

Last four digits of the card number.

expiration · object · required

Show properties

month · string

Two-digit expiration month.

year · string

Four-digit expiration year.

billing · object · required

Billing details for the cardholder.

Show properties

name · string · required

Full name.

phone · string

Phone number (E.164 format).

address · object

Billing address.

fundingType · string

Card funding type. Can be credit, debit, prepaid, or unknown.

bin · string

Bank Identification Number (first 6-8 digits of the card number).

country · string

Two-letter country code of the card issuer.

bankAccount · object

Bank account details. Present when type is bank-account-us, bank-account-mx-clabe, bank-account-co, or bank-account-sepa-iban.

Show common properties

billing · object · required

Billing details for the account holder.

Show properties

name · string · required

Full name.

phone · string

Phone number (E.164 format).

address · object

Show properties

line1 · string · required

line2 · string

city · string · required

stateOrRegion · string

postalCode · string · required

country · string · required

ISO 3166-1 alpha-2 country code.

bankName · string | null

Name of the bank. null if not resolvable.

accountSuffix · string · required

Last four digits of the account number, CLABE, or IBAN.

currency · string · required

ISO 4217 currency code (e.g. usd, mxn, eur, cop).

country · string · required

ISO 3166-1 alpha-2 country code.

entityType · string

Account holder type. Can be individual or business.

Show US-specific properties (bank-account-us)

bankAddress · object

Bank branch address.

routingNumber · string

Nine-digit ABA routing number.

accountType · string

checking or savings.

Show MX-specific properties (bank-account-mx-clabe)

bankCode · string

Three-digit bank code derived from the CLABE.

Show CO-specific properties (bank-account-co)

bankCode · string

Bank code assigned by Banco de la República.

accountType · string

checking or savings.

Show SEPA-specific properties (bank-account-sepa-iban)

bic · string

BIC/SWIFT code (8 or 11 characters).

Card

{
  "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": "[phone]",
      "address": {
        "line1": "123 Main St",
        "city": "Springfield",
        "stateOrRegion": "IL",
        "postalCode": "62701",
        "country": "US"
      }
    },
    "fundingType": "debit",
    "bin": "411111",
    "country": "US"
  }
}