> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Debit cards

> Use a debit card as an on-ramp funding source or an off-ramp payout destination in OMS.

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](#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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/payments/external-accounts) for the shared registration and lifecycle model.

## Related

* [Currencies and rails](/payments/core-concepts/currencies-and-rails): the full list of supported assets and rails
* [External accounts](/payments/external-accounts): the shared model for cards, banks, and external wallets
* [Transactions](/payments/transactions): the quote-and-execute flow for card and bank transfers