---
title: "Create a payment method"
method: POST
path: "/unstable/payment-methods"
tags: ["Payment Methods"]
---

# Create a payment method

`POST /unstable/payment-methods`

Saves a bank account payout method for a user so offramp orders can settle to it. Account numbers and IBANs are tokenized by the PCI-compliant vault before reaching Crossmint servers, so create requests must be submitted through `vault.crossmint.com`. Duplicate detection prevents saving the same account twice for the same user.

Supported types are the bank-account variants (`bank-account-us`, `bank-account-mx-clabe`, `bank-account-co`, `bank-account-sepa-iban`); the payout currency must match the account geography.

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

## Request body

- PmCreatePaymentMethodRequest — Create request for a bank account payout method. Provide the `bankAccount` sub-object with the fields required by the chosen `type`.
  - `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 must be provided.
  - `userLocator` string — Identifies the target user. Format: `<type>:<value>` (e.g., `email:alice@example.com`, `userId:abc123`). Required when authenticating with a server API key; ignored with JWT (the JWT subject is used instead).
  - `bankAccount` object — Bank account details. Required when `type` is a bank type. The exact fields depend on the country-specific type. Account numbers and IBANs are tokenized by the vault.
    - `accountNumber` string — Bank account number. For US: 4-17 digits. For MX: 18-digit CLABE. For CO: account number. Tokenized by the vault — never stored in plaintext.
    - `routingNumber` string — Nine-digit ABA routing transit number with checksum validation. US bank accounts only.
    - `iban` string — IBAN (ISO 13616, 15-34 characters). Tokenized by the vault — never stored in plaintext. SEPA only.
    - `bic` string — BIC/SWIFT code (ISO 9362, 8 or 11 uppercase alphanumeric characters). Optional — under EPC IBAN-only rules, the BIC can be derived from the IBAN. SEPA only.
    - `bankName` string — Name of the bank (e.g., "Wells Fargo", "Deutsche Bank"). Required for US; optional for SEPA.
    - `bankAddress` object — Bank branch mailing address. US bank accounts only.
    - `bankCode` string — Bank code. For MX: 3-digit code from the CLABE. For CO: code assigned by Banco de la República.
    - `accountType` 'checking' | 'savings' — Account type: `checking` or `savings`. Required for US and CO bank accounts.
    - `documentType` string — Colombian document type: `CC` (Cédula), `NIT` (Tax ID), `CE` (Cédula de Extranjería), `PASS` (Passport), or `PEP` (Special Permit). CO only.
    - `documentNumber` string — Document number matching `documentType`. Tokenized by the vault. CO only.
    - `billing` object, required — Account holder billing details. `name` is always required.
      - `name` string, required — Account holder full legal name.
      - `phone` string — Phone number in E.164 format (e.g., `+4915112345678`).
      - `address` object — Billing address. When provided, `line1`, `city`, `postalCode`, and `country` 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 — State, province, or region (max 50 characters). Required for all types except SEPA.
        - `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`).
    - `currency` string, required — ISO 4217 currency code in lowercase. Must match the type: `usd` for US, `mxn` for MX, `cop` for CO, `eur` for SEPA.
    - `country` string, required — ISO 3166-1 alpha-2 country code. For SEPA, must be one of the 37 EPC member states or Gibraltar.
    - `entityType` 'individual' | 'business', required — Account holder type: `individual` or `business`. SEPA does not currently support `business`.

## Response `201`

Payment method created successfully. Returns the full PaymentMethod object including the derived `displayName` and the `bankAccount` sub-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` — Request validation failed or duplicate payment method.
- `401` — Missing or invalid API key.
- `403` — Authentication source not allowed or required add-on not enabled.
- `422` — Request body failed schema validation.
- `429` — Rate limit exceeded.

---

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