Skip to main content
A debit card lets a customer fund a buy from their card and receive sell proceeds on it. Both directions use the standard quote-and-transaction flow:
  • Buy: OMS pulls US dollars from the card and delivers crypto to a wallet.
  • Sell: OMS sells crypto and pushes the dollars to the card.
A registered card is an external account with type: card and an ext_ ID. Every later quote references that ID. Only debit cards are accepted, and only individual customers can register one. Card numbers and security codes never touch your systems. Customers type them into secure fields from the OMS browser SDK, which replace both with aliases before the request reaches OMS. The SDK submits the aliased card to POST /external-accounts/cards. In production that endpoint accepts only aliases, so never send card numbers or security codes from your servers.
To register a card and run your first card transaction, follow Accept and pay out to debit cards.

How registration works

  1. Your page renders the card form with your publishable key and the customer’s ID.
  2. When the customer submits, the SDK asks your server for a customer token, and OMS checks your page’s origin against the publishable key while it starts a fraud-screening session.
  3. The SDK asks your server for a fresh customer token to authorize the card write.
  4. The card vault posts the form to the OMS secure host and replaces the card number and CVV with aliases on the way.
  5. OMS registers the card with the card processor. The card starts as pending and moves to active once the processor verifies it.
Only debit cards are accepted.

Test cards

In sandbox, register a card by entering one of these numbers in the OMS card form, with any future expiry date and any three-digit security code. To run the card form against sandbox, see Test in sandbox and on localhost.
These numbers aren’t real cards and work only in sandbox. They won’t work in production, and you must not enter a real card in sandbox.

The card object

A registered card is an external account with type: card. Registration returns 201 Created, normally with the account in pending:
OMS works out the brand and card type from the card number. The full card number and CVV are never returned. billingAddressSource is provided when the registration carried a billing address and customerDefault when OMS filled it from the customer’s address. If the billing country or the customer’s country is prohibited, registration still returns 201 Created, but the account is already rejected with failure.code set to countryProhibited.

Cardholder name

The cardholder name is always the customer’s own firstName and lastName; any name sent with the billing address is ignored. OMS normalizes the name before it reaches the processor (folds Latin letters to ASCII, drops apostrophes, turns dashes into spaces, collapses whitespace), so "José O'Brien-Smith" is sent as Jose / OBrien Smith. A name that still cannot be used (blank, a placeholder, non-letter characters, under 3 letters in total, or over 35 characters per part) is rejected with 422 CardholderNameInvalid (code 10380) before anything is stored. Correct the customer’s name, then register the card again.

Billing address

The billing address belongs to the card, not the customer’s KYC record, and the card processor uses it for address verification. If you omit it, OMS uses the customer’s residential address. If the customer has no usable address, registration fails with 422 MissingBillingAddress. OMS requires line1, city, state, zipCode, and country, where country is a two-letter ISO 3166-1 code such as US. line2 is optional. OMS also checks line1 and line2 against what the card processor accepts, and the SDK form runs the same checks before it submits. Each line:
  • Is at most 35 characters.
  • Isn’t a PO Box and isn’t only digits.
  • Contains none of these characters: ! @ # $ % ^ & * ( ) + = < > . , ; : ? " / \ | { } [ ] ~ _. Write 11 Creekside St, not 11 Creekside St.
A line that breaks these rules returns 422 BillingAddressInvalid. OMS applies the same rules to the customer’s address when it fills the billing address from it, so a registration without a billing address can fail with an error about the customer’s address. Send a billing address or correct the customer’s address.

Statuses

To track the move from pending, subscribe to the externalAccount.statusChanged webhook or poll GET /external-accounts/{id}. See External accounts for the failure object. Only label and metadata can be changed after registration, with PATCH /external-accounts/{id}. To change card details, register a new card and delete the old one.

On a quote

A card is a quote source for a buy and a destination for a sell. The card side is always { "type": "card", "details": { "id": "ext_…", "asset": "usd" } }; OMS infers the card network. The card must be active. A card transaction needs fraud-screening signals from the customer’s browser: POST /transactions takes webSessionId and deviceFingerprint as top-level fields alongside quoteId. Without webSessionId it returns 422 RiskSessionRequired. See Execute the transaction.

Webhook events

Cards emit the same events as other external accounts: See Webhook events for the envelope.

Errors

Most errors use the standard envelope. Branch on error or code, never on msg or cause:
On the registration path the OMS card form turns these into field errors and recovery states, so you mainly see them while debugging. A card the processor already holds, possibly for another platform, returns 409 in the short envelope, with code set to externalAccountAlreadyRegistered and error set to a message:

Key operations