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

# 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-sepa-iban` | Bank account identified by an IBAN within the supported SEPA scope. |
| `bank-account-co` | Colombian bank account (institution ID + account number + national document). |
| `bre-b` | Colombian Bre-B key: an `@handle`, a mobile number, an e-mail, an identity document, or a commerce code. |
| `bank-account-id` | Indonesian bank account (institution ID + account number), paid out over BI-FAST. |
| `bank-account-mx-clabe` | Mexican bank account, identified by an 18-digit CLABE (Clave Bancaria Estandarizada). |
| `bank-account-ng` | Nigerian bank account (institution ID + 10-digit NUBAN, the Nigeria Uniform Bank Account Number), paid out over NIP. |
| `bank-account-ph` | Philippine bank account (institution ID + account number), paid out over InstaPay or PESONet. |
| `bank-account-th` | Thai bank account (institution ID + account number), paid out over PromptPay. |
| `bank-account-vn` | Vietnamese bank account (institution ID + account number), paid out over Napas 247 or CITAD. |

<Note>
  `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.
</Note>

## Attributes

<ResponseField name="paymentMethodId" type="string" required>
  Unique identifier for the payment method.
</ResponseField>

<ResponseField name="default" type="boolean">
  Whether this is the user's default payment method. Returned for `card` and `bank-account-sepa-iban` only.
</ResponseField>

<ResponseField name="displayName" type="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.
</ResponseField>

<ResponseField name="type" type="string" required>
  Payment method type. One of `card`, `bank-account-us`, `bank-account-sepa-iban`, `bank-account-co`, `bre-b`, `bank-account-id`, `bank-account-mx-clabe`, `bank-account-ng`, `bank-account-ph`, `bank-account-th`, or `bank-account-vn`.
</ResponseField>

<ResponseField name="status" type="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`: the destination cannot receive a supported payout. The initial checks ended without a usable record, a provider refused the account, or the bank returned a payout to it. Retrying requires a new payment method.
  * `deleted`: removed by the client. Never reactivates.

  `pending` moves to `active`, `rejected`, or `deleted`; `active` moves to `rejected` or `deleted`; `rejected` moves 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](/offramp/guides/collect-bank-accounts#statuses).
</ResponseField>

<ResponseField name="statusReason" type="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.
</ResponseField>

<ResponseField name="card" type="object">
  Card details. Present when `type` is `card`.

  <Expandable title="properties">
    <ResponseField name="brand" type="string" required>
      Card brand. Can be `visa`, `mastercard`, `amex`, `discover`, `jcb`, `unionpay`, or `diners-club`.
    </ResponseField>

    <ResponseField name="last4" type="string" required>
      Last four digits of the card number.
    </ResponseField>

    <ResponseField name="expiration" type="object" required>
      <Expandable title="properties">
        <ResponseField name="month" type="string">
          Two-digit expiration month.
        </ResponseField>

        <ResponseField name="year" type="string">
          Four-digit expiration year.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="billing" type="object" required>
      Billing details for the cardholder.

      <Expandable title="properties">
        <ResponseField name="name" type="string" required>
          Full name.
        </ResponseField>

        <ResponseField name="phone" type="string">
          Phone number (E.164 format).
        </ResponseField>

        <ResponseField name="address" type="object">
          Billing address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fundingType" type="string">
      Card funding type. Can be `credit`, `debit`, `prepaid`, or `unknown`.
    </ResponseField>

    <ResponseField name="bin" type="string">
      Bank Identification Number (first 6-8 digits of the card number).
    </ResponseField>

    <ResponseField name="country" type="string">
      Two-letter country code of the card issuer.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="bankAccount" type="object">
  Bank account details. Present when `type` is `bank-account-us`, `bank-account-sepa-iban`, `bank-account-co`, `bank-account-id`, `bank-account-mx-clabe`, `bank-account-ng`, `bank-account-ph`, `bank-account-th`, or `bank-account-vn`. A `bre-b` method returns `breB` instead.

  <Expandable title="common properties">
    <ResponseField name="accountHolder" type="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.

      <Expandable title="properties">
        <ResponseField name="name" type="string" required>
          Full legal name.
        </ResponseField>

        <ResponseField name="email" type="string">
          E-mail address.
        </ResponseField>

        <ResponseField name="phoneNumber" type="string">
          Phone number (E.164 format).
        </ResponseField>

        <ResponseField name="address" type="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`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="bankName" type="string | null">
      Name of the bank. `null` if not resolvable. Absent for `bank-account-co`, `bank-account-id`, `bank-account-mx-clabe`, `bank-account-ng`, `bank-account-ph`, `bank-account-th`, and `bank-account-vn`.
    </ResponseField>

    <ResponseField name="accountSuffix" type="string" required>
      Last four digits of the account number, CLABE, or IBAN.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      ISO 4217 currency code (e.g. `usd`, `mxn`, `eur`, `cop`).
    </ResponseField>

    <ResponseField name="country" type="string" required>
      ISO 3166-1 alpha-2 country code.
    </ResponseField>

    <ResponseField name="entityType" type="string">
      Account holder type. `individual` or `business`. Required on creation. May be absent on records created before the field was enforced.
    </ResponseField>

    <ResponseField name="rails" type="object">
      Read-only. The payout rails a currently-available provider has confirmed for this account. Absent when no payout provider currently serves the account.

      <Expandable title="properties">
        <ResponseField name="status" type="string" required>
          `pending` while asynchronous rail resolution is still running for optional rails (baseline rails appear immediately); `complete` once resolved.
        </ResponseField>

        <ResponseField name="supported" type="string[]" required>
          Rail values this account supports. See [Payment Schemes](/offramp/payment-methods) for the current rail catalog and indicative delivery times.
        </ResponseField>

        <ResponseField name="pending" type="string[]" required>
          Rails still being resolved. Non-empty only while `status` is `pending`; `[]` once `status` is `complete`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  <Expandable title="US-specific properties (bank-account-us)">
    <ResponseField name="bankAddress" type="object">
      Bank branch address.
    </ResponseField>

    <ResponseField name="routingNumber" type="string">
      Nine-digit ABA routing number.
    </ResponseField>

    <ResponseField name="accountType" type="string">
      `checking` or `savings`.
    </ResponseField>
  </Expandable>

  <Expandable title="SEPA-specific properties (bank-account-sepa-iban)">
    <ResponseField name="bic" type="string">
      BIC/SWIFT code (8 or 11 characters).
    </ResponseField>
  </Expandable>

  <Expandable title="CO-specific properties (bank-account-co)">
    <ResponseField name="institutionId" type="string">
      Identifier of the bank that holds the account, for example `co-bancolombia`. See [Bank Institution IDs](/offramp/guides/bank-institution-ids).
    </ResponseField>

    <ResponseField name="accountType" type="string">
      `checking`, `savings`, or `electronic-deposit`.
    </ResponseField>

    <ResponseField name="accountHolder.document" type="object">
      The holder's national document. The full number is never returned.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          One of `cc`, `nit`, `ce`, `pa`, `ppt`, `ti`, `rc`, `te`, or `die`.
        </ResponseField>

        <ResponseField name="suffix" type="string">
          Last four digits of the document number.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  <Expandable title="Local bank properties (bank-account-id, bank-account-ng, bank-account-ph, bank-account-th, bank-account-vn)">
    <ResponseField name="institutionId" type="string">
      Identifier of the bank that holds the account, for example `id-bca`. See [Bank Institution IDs](/offramp/guides/bank-institution-ids).
    </ResponseField>

    <ResponseField name="accountType" type="string">
      `checking` or `savings`. Present when sent on creation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="breB" type="object">
  Bre-B key details. Present when `type` is `bre-b`, in place of `bankAccount`. The key itself is never returned.

  <Expandable title="properties">
    <ResponseField name="accountHolder" type="object">
      The person or company that owns the key. Always the value the client sent.

      <Expandable title="properties">
        <ResponseField name="name" type="string" required>
          Full legal name.
        </ResponseField>

        <ResponseField name="email" type="string">
          E-mail address.
        </ResponseField>

        <ResponseField name="phoneNumber" type="string">
          Phone number (E.164 format).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="accountSuffix" type="string" required>
      Masked form of the key. An e-mail key is masked in place. Every other key shows its last four characters.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Always `cop`. Bre-B only settles in Colombian pesos.
    </ResponseField>

    <ResponseField name="country" type="string" required>
      Always `CO`.
    </ResponseField>

    <ResponseField name="entityType" type="string">
      Key holder type. `individual` or `business`.
    </ResponseField>

    <ResponseField name="keyType" type="string">
      Category of the key, derived from its format. One of `alphanumeric`, `phone`, `email`, `identification`, or `commerce`. A client-supplied value is refused.
    </ResponseField>

    <ResponseField name="institutionName" type="string">
      Display name of the institution that holds the key. Absent until a name source answers.
    </ResponseField>

    <ResponseField name="rails" type="object">
      Read-only. The payout rails a currently-available provider advertises for this key. Absent when no provider serves the key.

      <Expandable title="properties">
        <ResponseField name="supported" type="string[]" required>
          Rail values this key supports. Bre-B carries `supported` alone, without the `status` and `pending` fields an ordinary bank account returns.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="label" type="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.
</ResponseField>

<ResponseField name="lastPayoutAt" type="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.
</ResponseField>

<ResponseExample>
  ```json Card theme={null}
  {
    "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"
    }
  }
  ```

  ```json US Bank Account theme={null}
  {
    "paymentMethodId": "f2ecef7e-91af-4fa7-93f9-12db856c227f",
    "type": "bank-account-us",
    "bankAccount": {
      "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",
      "rails": { "status": "complete", "supported": ["rtp", "ach-same-day", "ach-us"], "pending": [] }
    }
  }
  ```

  ```json SEPA theme={null}
  {
    "paymentMethodId": "3323460b-d9d2-4ec6-b380-8a3e01e3f226",
    "default": false,
    "displayName": "Deutsche Bank ••6789",
    "type": "bank-account-sepa-iban",
    "bankAccount": {
      "bankName": "Deutsche Bank",
      "accountSuffix": "6789",
      "currency": "eur",
      "country": "DE",
      "entityType": "individual",
      "bic": "COBADEFFXXX"
    }
  }
  ```

  ```json CO Bank Account theme={null}
  {
    "paymentMethodId": "1cad2281-bd3d-4219-8787-7dfea94c60b1",
    "type": "bank-account-co",
    "bankAccount": {
      "accountSuffix": "7320",
      "institutionId": "co-bancolombia",
      "accountType": "checking",
      "currency": "cop",
      "country": "CO",
      "entityType": "individual",
      "accountHolder": { "name": "Camila Restrepo", "document": { "type": "cc", "suffix": "4050" } },
      "rails": { "status": "pending", "supported": [], "pending": ["ach-credit"] }
    }
  }
  ```

  ```json CO Bre-B key theme={null}
  {
    "paymentMethodId": "9f1a6b2c-3d4e-4f50-9a61-2b3c4d5e6f70",
    "type": "bre-b",
    "status": "active",
    "statusReason": null,
    "breB": {
      "accountHolder": {
        "name": "Carlos Gómez",
        "phoneNumber": "+573001234567"
      },
      "accountSuffix": "CDKS",
      "currency": "cop",
      "country": "CO",
      "entityType": "individual",
      "keyType": "alphanumeric"
    }
  }
  ```

  ```json ID Bank Account theme={null}
  {
    "paymentMethodId": "7a3e5c91-2b4d-4f86-a1c0-9d8e7f6a5b42",
    "type": "bank-account-id",
    "bankAccount": {
      "accountSuffix": "7890",
      "institutionId": "id-bca",
      "currency": "idr",
      "country": "ID",
      "entityType": "individual",
      "accountHolder": { "name": "Budi Santoso" },
      "rails": { "status": "complete", "supported": ["bi-fast"], "pending": [] }
    }
  }
  ```

  ```json MX Bank Account theme={null}
  {
    "paymentMethodId": "27bacbe1-d0ff-4bc3-b37a-ca91cc64fa39",
    "type": "bank-account-mx-clabe",
    "bankAccount": {
      "accountHolder": {
        "name": "Luis Gomez Rios",
        "phoneNumber": "+525512345678"
      },
      "accountSuffix": "7899",
      "currency": "mxn",
      "country": "MX",
      "entityType": "individual"
    }
  }
  ```

  ```json NG Bank Account theme={null}
  {
    "paymentMethodId": "2e9b4d17-6a3c-4f85-b1d0-8c7e5a2f9b63",
    "type": "bank-account-ng",
    "bankAccount": {
      "accountSuffix": "7897",
      "institutionId": "ng-gt-bank",
      "currency": "ngn",
      "country": "NG",
      "entityType": "individual",
      "accountHolder": { "name": "Chinedu Okafor" },
      "rails": { "status": "complete", "supported": ["nip"], "pending": [] }
    }
  }
  ```

  ```json PH Bank Account theme={null}
  {
    "paymentMethodId": "5e2b7c41-9d0a-4f3b-8c6d-2a1b3c4d5e6f",
    "type": "bank-account-ph",
    "bankAccount": {
      "accountSuffix": "7890",
      "institutionId": "ph-bdo",
      "currency": "php",
      "country": "PH",
      "entityType": "individual",
      "accountHolder": { "name": "Maria Santos" },
      "rails": { "status": "complete", "supported": ["instapay", "pesonet"], "pending": [] }
    }
  }
  ```

  ```json TH Bank Account theme={null}
  {
    "paymentMethodId": "8a4c7e39-2f1b-4d96-b3e5-7c0d2a9f6b41",
    "type": "bank-account-th",
    "bankAccount": {
      "accountSuffix": "7890",
      "institutionId": "th-kasikorn-bank",
      "currency": "thb",
      "country": "TH",
      "entityType": "individual",
      "accountHolder": { "name": "Somchai Jaidee" },
      "rails": { "status": "complete", "supported": ["promptpay"], "pending": [] }
    }
  }
  ```

  ```json VN Bank Account theme={null}
  {
    "paymentMethodId": "3f7d1b86-9e2a-4c50-8d34-1a6e9b7c5f02",
    "type": "bank-account-vn",
    "bankAccount": {
      "accountSuffix": "4567",
      "institutionId": "vn-acb",
      "currency": "vnd",
      "country": "VN",
      "entityType": "individual",
      "accountHolder": { "name": "Nguyễn Văn An" },
      "rails": { "status": "complete", "supported": ["napas-247", "citad"], "pending": [] }
    }
  }
  ```
</ResponseExample>