Save a Payment Method
The request body depends on the payment methodtype. 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. The path carries the API version, /api/2026-09-16/payment-methods. The older /api/unstable/payment-methods path still works but is deprecated and will be removed once integrators have moved.
- US
- Europe (SEPA)
- Colombia (ACH)
- Colombia (Bre-B)
- Mexico (CLABE)
cURL
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. The examples show a payment method after its checks complete. A create response has status: pending.
- US
- Europe (SEPA)
- Colombia (ACH)
- Colombia (Bre-B)
- Mexico (CLABE)
bankAccount.accountSuffix, the last four digits, while routingNumber comes back in full because it is not secret. Crossmint checks the ABA routing check digit and rejects a bad routing number with 422. An active status does not establish that the account exists or who owns it; those checks run when you create an order. accountHolder.address and bankAddress are optional, and neither takes a country. 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.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.
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 Changes
Creation always returnspending. Poll the payment method to get its latest status, or receive a webhook when the status changes. A US or SEPA account usually becomes active within seconds. A Mexican CLABE or a Bre-B key can take several minutes, because a check with the bank runs first.
The allowed transitions are:
pending→active,rejected, ordeletedactive→rejectedwhen a provider refuses the account or the bank returns a payout to it, ordeletedrejected→deleted
active with the error code payments:payment-method.not-active. If a provider refuses the account, an active payment method changes to rejected. When this happens while you create or update the order, that request fails with the error code payments:payment-method.rejected-by-provider. If the payment method is deleted after the order is created and before the payout starts, the order fails. A refund of the deposit starts, except when a Colombian payout was set up before the check. An order that waits for deposit instructions also fails when its payment method is no longer active.
When the bank returns a payout because the account cannot receive it, every payment method for that account in your project changes to rejected, for all of your users. A deleted one stays deleted. statusReason gives the reason. A new payment method for that account in the same project then fails with the error code payments:payment-method.destination-blocked, and the error response carries the same statusReason:
Status Reasons
statusReason is null unless the payment method is rejected. A rejected method may include one of the following reason codes:
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.
Status Webhook
Crossmint sends thepayment_methods.status.updated webhook each time the stored status of a bank account or Bre-B payment method changes. Use it to avoid polling. In rare cases an event can be missing, so fetch the payment method when you need its current status, for example before you create an order.
Crossmint sends it for these changes:
pending→activepending→rejectedactive→rejected, when a provider refuses the account or the bank returns a payout to it- any status →
deleted, when you delete the payment method
- The status in the create response.
- A create request that fails because the account is blocked. That request returns
400. - A write that leaves the status the same, such as a repeat delete or a change of
statusReasonalone. - Card payment methods.
data.paymentMethod carries only these four fields. statusReason is null unless status is rejected. For every other field, retrieve the payment method with paymentMethodId.
The id has the form pm-status-<paymentMethodId>-<status>. It stays the same for one change, and a retry delivers the same id. Deduplicate on it in your handler.
Events can arrive out of order. Status only moves forward, in this order: pending, active, rejected, deleted. Ignore an event whose status comes before the status your handler already holds.
To receive the event, open Webhooks in the Crossmint console and subscribe an endpoint to payment_methods.status.updated. An endpoint with no event filter receives it without a subscription. Verify the signature as described in Verify Webhooks.
Rails
rails.supported lists the rails available to reach the destination straight away, and rails.pending lists rails that may become available once confirmed. rails.supported can list rails while the method is still pending. Only an active method accepts an order. A valid account with no rail to reach it is rejected with statusReason: "no-rail-available".
When you create an order, the payout provider can find that the account cannot receive one of the rails in rails.supported. Crossmint then stops listing that rail, and the payment method stays active. No webhook is sent, so refetch the payment method to read its current rails. If the order pays out on that rail, no funds move. When this happens while you create or update the order, that request fails with the error code payments:offramp.rail-not-supported. An order that waits for deposit instructions fails instead. Create the order again without a rail to pay out on a rail the account supports.
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, set the default payment method, or remove a payment method.Next Steps
Quickstart
Use a saved payment method in an offramp order
Institution IDs
Find the institutionId of a bank by country
Create Payment Method
Full request and response schema in the API reference