Debit cards - Polygon Developer Docs

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"
    }
  }
}

Field	Required	Meaning
`cardNumber`	Yes	The card number. Write-only; never returned or stored.
`cvv`	Yes	The card verification value. Write-only; never returned or stored.
`expiryMonth`, `expiryYear`	Yes	Expiry as integers (for example, `4` and `2028`).
`billingAddress`	Yes	The 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.
`cardProvider`	No	The card network: `visa`, `mastercard`, `amex`, or `discover`.
`webSessionId`	No	A 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.

Currencies and rails: the full list of supported assets and rails
External accounts: the shared model for cards, banks, and external wallets
Transactions: the quote-and-execute flow for card and bank transfers

​Card as a funding source

​Card as a payout destination

​Settlement type

​Registering a card

​Related

Card as a funding source

Card as a payout destination

Settlement type

Registering a card

Related