- 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.
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
- Your page renders the card form with your publishable key and the customer’s ID.
- 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.
- The SDK asks your server for a fresh customer token to authorize the card write.
- The card vault posts the form to the OMS secure host and replaces the card number and CVV with aliases on the way.
- OMS registers the card with the card processor. The card starts as
pendingand moves toactiveonce the processor verifies it.
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.- Mastercard Debit
- Visa Prepaid
- Visa Debit
The card object
A registered card is an external account withtype: card. Registration returns 201 Created, normally with the account in pending:
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 ownfirstName 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 with422 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:
! @ # $ % ^ & * ( ) + = < > . , ; : ? " / \ | { } [ ] ~ _. Write11 Creekside St, not11 Creekside St.
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 quotesource 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 onerror or code, never on msg or cause:
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
Related
- Accept and pay out to debit cards: register a card and run a card transaction, step by step
- External accounts: the shared model for cards, banks, and external wallets
- Transactions: the quote-and-execute flow