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 (Clave Bancaria Estandarizada).
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.
bre-b	Colombian Bre-B key: an @handle, a mobile number, an e-mail, an identity document, or a commerce code.

bank-account-sepa-iban is the payment-method type; sepa and sepa-instant are rail values within it. A SEPA IBAN account can support both rails.

Attributes

paymentMethodId · string · required

Unique identifier for the payment method.

default · boolean

Whether this is the user’s default payment method. Returned for card and bank-account-sepa-iban only.

displayName · string

Server-derived label, returned for card and bank-account-sepa-iban only (e.g. "Visa ••1111", "Deutsche Bank ••6789"). Absent on every other bank-account type; read label there.

type · string · required

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

status · string

Bank accounts and Bre-B keys only. Readiness of the destination, not user approval, ownership, or a guaranteed payout. One of:

• pending: initial readiness checks are running.
• active: required readiness checks passed. Orders still run their own eligibility checks.
• rejected: initial checks ended without a usable record. Retrying requires a new payment method.
• deleted: removed by the client, or by Crossmint after a confirmed account closure. Never reactivates.

pending moves to active, rejected, or deleted; active and rejected move only to deleted. Creation starts the readiness checks once; reads, label edits, and orders never restart them. Treat an unrecognized status as not ready for orders. See Manage Payment Methods.

statusReason · string | null

Always null except on a rejected method, where it may be destination-not-found, destination-closed, destination-cannot-receive, or no-rail-available. null when no safe destination condition was established. Never carries provider errors or compliance detail. Codes are extensible, so tolerate unknown values.

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. A bre-b method returns breB instead.

Show common properties

accountHolder · object

The person or company that owns the account. Always the value the client sent, never the bank’s record of the holder. Derived from billing when the record predates this field.

Show properties

name · string · required

Full legal name.

email · string

E-mail address.

phoneNumber · string

Phone number (E.164 format).

address · object

Holder address, without a country: the account’s own country is the bank’s jurisdiction. Present only on types that collect one. Never on bank-account-mx-clabe.

bankName · string | null

Name of the bank. null if not resolvable. Absent for bank-account-mx-clabe, which returns institutionName instead.

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. individual or business. Required on creation. May be absent on records created before the field was enforced.

rails · object

Read-only. The payout rails a currently-available provider has confirmed for this account. Absent when no payout provider currently serves the account.

Show properties

status · string · required

pending while asynchronous rail resolution is still running for optional rails (baseline rails appear immediately); complete once resolved.

supported · string[] · required

Rail values this account supports. See Payment Schemes for the current rail catalog and indicative delivery times.

pending · string[] · required

Rails still being resolved. Non-empty only while status is pending; [] once status is complete.

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.

institutionName · string

Display-only name of the institution holding the CLABE. Absent until the destination lookup answers. Not bankName: a large share of CLABEs are issued by STP and the fintechs that ride on it.

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).

breB · object

Bre-B key details. Present when type is bre-b, in place of bankAccount. The key itself is never returned.

Show properties

accountHolder · object

The person or company that owns the key. Always the value the client sent.

Show properties

name · string · required

Full legal name.

email · string

E-mail address.

phoneNumber · string

Phone number (E.164 format).

accountSuffix · string · required

Masked form of the key. An e-mail key is masked in place. Every other key shows its last four characters.

currency · string · required

Always cop. Bre-B only settles in Colombian pesos.

country · string · required

Always CO.

entityType · string

Key holder type. individual or business.

keyType · string

Category of the key, derived from its format. One of alphanumeric, phone, email, identification, or commerce. A client-supplied value is refused.

institutionName · string

Display name of the institution that holds the key. Absent until a name source answers.

rails · object

Read-only. The payout rails a currently-available provider advertises for this key. Absent when no provider serves the key.

Show properties

supported · string[] · required

Rail values this key supports. Bre-B carries supported alone, without the status and pending fields an ordinary bank account returns.

label · string

Bank accounts only. The client’s own name for this payment method, when one was sent on creation. At most 255 characters. A card request does not accept it.

lastPayoutAt · string

Read-only. Bank accounts only. ISO 8601 timestamp of the most recent successful offramp payout funded by this account. Absent until the first payout.

CO Bre-B key

{
  "paymentMethodId": "9f1a6b2c-3d4e-4f50-9a61-2b3c4d5e6f70",
  "type": "bre-b",
  "status": "active",
  "statusReason": null,
  "breB": {
    "accountHolder": {
      "name": "Carlos Gómez",
      "phoneNumber": "[phone]"
    },
    "accountSuffix": "CDKS",
    "currency": "cop",
    "country": "CO",
    "entityType": "individual",
    "keyType": "alphanumeric"
  }
}