Manage Payment Methods

Before creating an offramp order, save the destination bank account as a payment method. Saved payment methods can be reused across Crossmint products, so users only need to enter their bank details once.

Save a Payment Method

The request body depends on the payment method type. See The Payment Method Object for the full list of types and fields. The examples below use the staging URL, https://vault.staging.crossmint.com. In production, use https://vault.crossmint.com.

US
Europe (SEPA)
Mexico (CLABE)
Colombia
Colombia (Bre-B)

cURL

curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bank-account-us",
    "userLocator": "<USER_LOCATOR>",
    "label": "Wells Fargo Checking",
    "bankAccount": {
      "accountNumber": "<ACCOUNT_NUMBER>",
      "routingNumber": "091300010",
      "accountType": "checking",
      "entityType": "individual",
      "accountHolder": {
        "name": "Emily Carter"
      }
    }
  }'

cURL

curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bank-account-sepa-iban",
    "userLocator": "<USER_LOCATOR>",
    "label": "My Wise EUR",
    "bankAccount": {
      "iban": "BE05100052384175",
      "bic": "TRWIBEB1XXX",
      "entityType": "individual",
      "accountHolder": {
        "name": "Lukas Meier"
      }
    }
  }'

cURL

curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bank-account-mx-clabe",
    "userLocator": "<USER_LOCATOR>",
    "label": "Mi cuenta Nu",
    "bankAccount": {
      "clabe": "646180527394108255",
      "entityType": "individual",
      "accountHolder": {
        "name": "Andrea Fuentes Lopez"
      }
    }
  }'

cURL

curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bank-account-co",
    "userLocator": "<USER_LOCATOR>",
    "label": "Mi Bancolombia",
    "bankAccount": {
      "accountNumber": "2048817320",
      "bankCode": "1007",
      "accountType": "checking",
      "entityType": "individual",
      "accountHolder": {
        "name": "Camila Restrepo"
      }
    }
  }'

cURL

curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bre-b",
    "userLocator": "<USER_LOCATOR>",
    "label": "Nequi Ahorros",
    "breB": {
      "key": "@MQ7RK2PLTA",
      "entityType": "individual",
      "accountHolder": {
        "name": "Santiago Vargas"
      }
    }
  }'

The response returns the saved payment method, including its paymentMethodId and a masked accountSuffix. Account numbers, IBANs, CLABEs, and Bre-B keys never appear in full. Pass the paymentMethodId as the recipient when you create an order.

US
Europe (SEPA)
Mexico (CLABE)
Colombia
Colombia (Bre-B)

{
  "type": "bank-account-us",
  "paymentMethodId": "57d99e28-8fad-4158-b825-75a693e44b10",
  "status": "active",
  "statusReason": null,
  "label": "Wells Fargo Checking",
  "bankAccount": {
    "accountSuffix": "<LAST_4_DIGITS>",
    "routingNumber": "091300010",
    "accountType": "checking",
    "currency": "usd",
    "country": "US",
    "entityType": "individual",
    "accountHolder": {
      "name": "Emily Carter"
    },
    "rails": {
      "supported": [
        "ach-credit",
        "same-day-ach-credit"
      ],
      "pending": [
        "rtp-credit"
      ]
    }
  },
  "createdAt": "2026-08-20T19:10:00.000Z",
  "updatedAt": "2026-08-20T19:10:00.000Z"
}

The full account number is never returned. The response carries bankAccount.accountSuffix, the last four digits, while routingNumber comes back in full because it is not secret. A create that passes the structural checks, such as the ABA routing check digit, returns status: "active" straight away. This does not establish that the account exists or who owns it; those checks run when you create an order. The available rails depend on the addresses you supply: fedwire appears in rails.supported only when both accountHolder.address and bankAddress are provided. rtp-credit starts in rails.pending because not every US bank participates in the RTP network, and it moves to rails.supported once the receiving bank’s participation is confirmed. institutionName is never populated for US accounts.

{
  "type": "bank-account-sepa-iban",
  "paymentMethodId": "19ee530a-80b3-401c-9a53-d6886c22fdd4",
  "status": "active",
  "reason": null,
  "default": false,
  "displayName": "Wise ••4175",
  "display": {
    "label": "Wise ••4175"
  },
  "lastPayoutAt": "2026-09-15T22:00:51.733Z",
  "bankAccount": {
    "accountHolder": {
      "name": "Lukas Meier"
    },
    "bankName": "Wise",
    "accountSuffix": "4175",
    "currency": "eur",
    "country": "BE",
    "entityType": "individual",
    "bic": "TRWIBEB1XXX",
    "rails": {
      "status": "complete",
      "supported": [
        "sepa"
      ],
      "pending": []
    }
  },
  "createdAt": "2026-09-15T19:04:06.788Z",
  "updatedAt": "2026-09-15T22:00:55.633Z"
}

The full IBAN is never returned. The response carries bankAccount.accountSuffix, the last four characters. SEPA validation is structural only (the IBAN mod-97 check), so a create that passes it returns status: "active" straight away. This does not establish that the account exists or who owns it. currency and country are read-only and derived from the IBAN. bankName is display-only and provider-sourced, so it stays absent when unknown.

{
  "type": "bank-account-mx-clabe",
  "paymentMethodId": "ba4280b4-8fe3-41e5-9c38-f72d453c950f",
  "status": "active",
  "statusReason": null,
  "label": "Mi cuenta Nu",
  "bankAccount": {
    "accountHolder": {
      "name": "Andrea Fuentes Lopez"
    },
    "accountSuffix": "8255",
    "currency": "mxn",
    "country": "MX",
    "entityType": "individual",
    "bankCode": "646",
    "rails": {
      "status": "complete",
      "supported": [
        "spei"
      ],
      "pending": []
    }
  },
  "createdAt": "2026-09-17T14:16:38.552Z",
  "updatedAt": "2026-09-17T14:16:41.026Z"
}

The full CLABE is never returned. The response carries bankAccount.accountSuffix, the last four digits, and bankAccount.bankCode, derived from the first three. A malformed CLABE check digit is rejected synchronously with 422 and nothing is stored. institutionName is optional display metadata from a reliable bank directory and is omitted when unknown. accountHolder.name is always echoed back exactly as sent, and ownership is evaluated when you create an order, not on the payment method.

{
  "type": "bank-account-co",
  "paymentMethodId": "6b489a5d-3867-4ec9-bb76-072a89e1319d",
  "status": "active",
  "statusReason": null,
  "label": "Mi Bancolombia",
  "bankAccount": {
    "accountSuffix": "7320",
    "bankCode": "1007",
    "institutionName": "Bancolombia",
    "accountType": "checking",
    "currency": "cop",
    "country": "CO",
    "entityType": "individual",
    "accountHolder": {
      "name": "Camila Restrepo"
    },
    "rails": {
      "supported": [
        "ach-co-credit"
      ]
    }
  },
  "createdAt": "2026-08-21T22:10:00.000Z",
  "updatedAt": "2026-08-21T22:12:11.000Z"
}

The full account number is never returned. The response carries bankAccount.accountSuffix, the last four digits. institutionName is optional display metadata from a reliable bank directory and is omitted when unknown. accountHolder.name is always echoed back exactly as sent, and ownership is evaluated when you create an order, not on the payment method.

{
  "type": "bre-b",
  "paymentMethodId": "7fdf72b9-f627-4b89-b7d7-5795893aaf12",
  "status": "active",
  "statusReason": null,
  "label": "Nequi Ahorros",
  "breB": {
    "accountHolder": {
      "name": "Santiago Vargas"
    },
    "accountSuffix": "PLTA",
    "currency": "cop",
    "country": "CO",
    "entityType": "individual",
    "keyType": "alphanumeric",
    "rails": {
      "supported": [
        "bre-b"
      ]
    }
  },
  "createdAt": "2026-09-17T14:27:20.725Z",
  "updatedAt": "2026-09-17T14:27:21.410Z"
}

The key itself is never returned. The response carries breB.accountSuffix instead: the last four characters of the key’s distinguishing part, which for alphanumeric keys is everything after the leading @ and for email keys is the local part before the @. keyType is derived from the key format. institutionName is optional display metadata from a reliable bank directory and is omitted when unknown.

Saving a payment method does not require the user to be verified yet, but creating an order does. Before you offramp to it, verify the user and link the wallet they will pay from. See the Quickstart.

For a complete list of fields and supported payment method types, see The Payment Method Object in the API reference.

Statuses

Every payment method type shares one lifecycle. status describes whether the payment method has passed the readiness checks required for its type and can proceed to order-level eligibility checks. It does not describe user approval, ownership, or guaranteed payout success.

Status	Meaning
`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. To retry, create a new payment method.
`deleted`	Removed by you, or by Crossmint after a confirmed account closure. Never reactivates.

Status Changes

A payment method may complete its readiness checks during creation or initially return pending. If it is pending, poll the payment method to get its latest status. The allowed transitions are:

pending → active, rejected, or deleted
active → deleted
rejected → deleted

A deleted method never reactivates. Readiness checks start when the method is created. Fetching it, editing its label, or using it in an order does not restart those checks. A failed transfer also does not change the payment-method status by itself.

Status Reasons

statusReason is null unless the payment method is rejected. A rejected method may include one of the following reason codes:

Code	Meaning
`destination-not-found`	The account or key is confirmed not to exist.
`destination-closed`	The account is confirmed closed.
`destination-cannot-receive`	The destination cannot receive supported payouts.
`no-rail-available`	No supported payout rail reaches the destination. This is not a temporary outage.

Branch on status, never on statusReason. New codes can appear at any time, so tolerate values you do not recognize. statusReason never carries provider errors, ownership, or compliance detail. Ownership is evaluated when you create an order, not on the payment method.

Rails

rails.supported lists the rails available to reach the destination straight away, and rails.pending lists rails that may become available once confirmed. Only an active method has a non-empty rails.supported. A valid account with no rail to reach it is rejected with statusReason: "no-rail-available".

List, Update, and Remove

Reads and non-sensitive updates go through the standard API. Use it to list a user’s payment methods, fetch one, update the label or other non-sensitive metadata, or remove a payment method.

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Save a Payment Method

Statuses

Status Changes

Status Reasons

Rails

List, Update, and Remove

Next Steps

Quickstart

Create Payment Method

​Save a Payment Method

​Statuses

​Status Changes

​Status Reasons

​Rails

​List, Update, and Remove

​Next Steps

Quickstart

Create Payment Method

Save a Payment Method

Statuses

Status Changes

Status Reasons

Rails

List, Update, and Remove

Next Steps