Skip to main content
A debit card connects to OMS in two directions. As a funding source, a card payment converts to crypto and tops up a customer’s wallet (an on-ramp). As a payout destination, OMS pushes a wallet balance out to a cardholder’s debit card (an off-ramp). Both run through the standard quote-and-transaction flow; only the instrument changes. Card support requires the usd endorsement on the customer. A card is referenced by its ext_card_ external-account ID and always requires asset: usd; its network is inferred server-side. Register a card once with POST /external-accounts, then reference the returned ext_card_ ID on quotes. See Registering a card.

​
Card as a funding source

Reference the card as the quote source (pull-from-card). The customer pays with their card and OMS delivers crypto to the destination wallet. 
{
  "customerId": "cst_...",
  "source": {
    "type": "card",
    "details": { "id": "ext_card_...", "asset": "usd" },
    "amount": "100.00"
  },
  "destination": {
    "type": "walletOms",
    "details": { "id": "wlt_...", "asset": "usdc", "network": "polygon" }
  }
}

​
Card as a payout destination

Reference the card as the quote destination (push-to-card). OMS pushes the payout from an OMS wallet source to the card. 
{
  "customerId": "cst_...",
  "source": {
    "type": "walletOms",
    "details": { "id": "wlt_...", "asset": "usdc", "network": "polygon" },
    "amount": "100.00"
  },
  "destination": {
    "type": "card",
    "details": { "id": "ext_card_...", "asset": "usd" }
  }
}

​
Settlement type

The card rail accepts an optional settlementType on the quote request:
  • internal: OMS custodies the crypto.
  • external: the crypto settles to an on-chain wallet.
The default depends on direction: a card buy (pull-from-card) defaults to external, and a card sell (push-to-card) defaults to internal. The field is ignored for non-card rails.

​
Registering a card

Register a card with POST /external-accounts, using type: "card" and the card detail object. Cards use the same registration endpoint as every other external account type: 
{
  "owner": { "kind": "customer", "customerId": "cst_..." },
  "type": "card",
  "card": {
    "cardNumber": "4111111111111111",
    "cvv": "123",
    "expiryMonth": 4,
    "expiryYear": 2028,
    "cardProvider": "visa",
    "billingAddress": {
      "addressLine1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zipCode": "78701",
      "country": "US"
    }
  }
}
FieldRequiredMeaning
cardNumberYesThe card number. Write-only; never returned or stored.
cvvYesThe card verification value. Write-only; never returned or stored.
expiryMonth, expiryYearYesExpiry as integers (for example, 4 and 2028).
billingAddressYesThe billing address the card issuer has on file, used for AVS and fraud screening. addressLine1, city, state, zipCode, and country (ISO 3166-1 alpha-2) are required; addressLine2, firstName, and lastName are optional.
cardProviderNoThe card network: visa, mastercard, amex, or discover.
webSessionIdNoA fraud-screening web session identifier, forwarded to the card processor.
The billing address is a property of the card, not the customer’s KYC identity: a customer may register cards with differing billing addresses, so supply it per card rather than deriving it from the customer record. The response returns only cardNumberLast4, cardProvider, expiryMonth, and expiryYear; the full card number and CVV are never stored or echoed back. A card starts pending and flips to active (usable on quotes) or failed. See External accounts for the shared registration and lifecycle model.