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

# Cards

> Issue and manage virtual USD cards for your customers — one API, issuer abstracted.

Issue and manage virtual **USD cards** for your customers — usable for online purchases and
subscriptions anywhere the card network is accepted. You integrate one Numero card API — Numero handles issuing for you.

> **Full reference:** every card endpoint, request, and response is in the **API Reference** (tags
> **Cards** and **Cardholders**). This page is the orientation.

## Card type

Every card we issue is a **wallet-enabled USD virtual card** — usable online anywhere the network is
accepted, and eligible to be added to Apple Wallet or Google Wallet.

| Type                                                 | `capability`                        | Use for                                                                        |
| ---------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------ |
| **Wallet-enabled USD card** (Apple Pay / Google Pay) | omit, or `APPLE_PAY` / `GOOGLE_PAY` | Online purchases, subscriptions, ad spend — and adding to Apple/Google Wallet. |

Omitting `capability` gives you the same card — it is the only type we issue.

Discover which products and capabilities are available to your business with
`GET /business/card/products` (don't hardcode product codes). The card you get back echoes its
`capabilities`, so you can confirm the type you issued.

> Wallet-enabled means the card is eligible to be added to Apple/Google Wallet (the cardholder adds it
> with the card details). In-app push-provisioning ("Add to Apple Wallet" button) is a separate flow we
> don't expose yet.

## Two ways to use it

1. **Issue directly** — `POST /business/card/issue` with the cardholder's KYC inline. Numero
   creates (or reuses) the cardholder for you and mints the card.
2. **Customer-first (BaaS)** — create a **cardholder** once (`POST /business/cardholders`), then issue
   one or more cards to them (`POST /business/cardholders/{customerId}/cards`). Best when you manage many
   end-customers; each cardholder has their own profile, cards, and statement.

## Base URL & auth

Card endpoints are part of the standard business API — **same base URL and API key** as every other
`/business/*` endpoint (there is no separate cards host):

| Environment | Base URL                                         |
| ----------- | ------------------------------------------------ |
| Sandbox     | `https://api.usenumero.com/numeroaccount/api/v1` |
| Production  | `https://api.usenumero.com/numeroaccount/api/v1` |

Authenticate with your `X-Numero-Api-Key` header (same as Balance, Transfers, VAS, etc.). **Every
card and cardholder endpoint is signature-gated** — send `X-Numero-Signature` and
`X-Numero-Signature-Version: v2` as well. See [Request signing](/03-request-signing).

## Prerequisites (fund-first + entitlement)

1. **Entitlement** — your business must be approved for the card product. Request it in
   Dashboard → Cards (or it's provisioned for you); an approved entitlement opens your **USD card wallet**.
2. **Fund the USD card wallet** — card issuance and top-ups debit this wallet (fund-first). Fund it from your dashboard
   (convert NGN→USD into the card wallet).

If you're not approved, issue calls return `approval_required`.

## Endpoints

| Method | Endpoint                                          | Description                                          |
| ------ | ------------------------------------------------- | ---------------------------------------------------- |
| GET    | `/business/card/products`                         | List available products + capabilities + entitlement |
| POST   | `/business/card/issue`                            | Issue a card (KYC inline)                            |
| GET    | `/business/card`                                  | List your cards                                      |
| GET    | `/business/card/{reference}`                      | Get a card (masked)                                  |
| POST   | `/business/card/{reference}/topup`                | Fund a card                                          |
| POST   | `/business/card/{reference}/withdraw`             | Withdraw from a card                                 |
| POST   | `/business/card/{reference}/freeze`               | Freeze a card                                        |
| POST   | `/business/card/{reference}/unfreeze`             | Unfreeze a card                                      |
| POST   | `/business/card/{reference}/limits`               | Set daily / per-transaction limits                   |
| POST   | `/business/card/{reference}/reveal`               | Reveal full PAN/CVV (sensitive)                      |
| GET    | `/business/card/{reference}/transactions`         | Card statement                                       |
| POST   | `/business/cardholders`                           | Create a cardholder                                  |
| GET    | `/business/cardholders`                           | List cardholders                                     |
| GET    | `/business/cardholders/{customerId}`              | Get a cardholder                                     |
| GET    | `/business/cardholders/{customerId}/cards`        | A cardholder's cards                                 |
| POST   | `/business/cardholders/{customerId}/cards`        | Issue a card to a cardholder                         |
| GET    | `/business/cardholders/{customerId}/transactions` | Cardholder statement                                 |

## Card balances

Cards are prefunded: a card's `balance` is what is available to spend on that card, in the card's
currency. Fund it with [top-up](/api-reference/cards-topup) and take funds back with
[withdraw](/api-reference/cards-withdraw); spend, settlement, refund, reversal, cross-border and decline
activity are all reflected in it.

The `balance` Numero returns is the authoritative figure for the card — read it from the card endpoints
rather than deriving your own running total from the statement.

## Statuses

`Pending` → `Active` → `Frozen` (reversible) / `Terminated` (final). Three consecutive
insufficient-balance declines auto-terminate a card.

## Reveal is sensitive

`/reveal` returns the full PAN, CVV, and expiry, fetched live from the issuer — Numero never stores the
full PAN. Only call it from a PCI-aware context, and never log it.

## Statements & billing

* **Card statement** (`/{reference}/transactions`) = per-card spend (settlement, refund, cross-border…).
* **USD card-wallet statement** (your wallet transactions: funding, top-ups, fees) is separate.
* A **monthly card invoice** aggregates the card processing charges on your account and is auto-debited
  from your USD card wallet (a deficit is carried if underfunded). View invoices in
  Dashboard → Cards → Invoices.

## Chargebacks

Lodge a chargeback against a card transaction from the **Dashboard** (Cards → card → Dispute), not via
the API. Numero files it with the card network; a chargeback fee applies.