Full reference: every card endpoint, request, and response is in the API Reference (tags Cards and Cardholders). This page is the orientation.
Card types
We issue two types of USD virtual card. You choose at issue time with thecapability field — the
issuer is selected for you.
| Type | capability | Use for |
|---|---|---|
| Plain USD virtual card | omit, or USD | Online purchases, subscriptions, ad spend. |
| Wallet-enabled USD card (Apple Pay / Google Pay) | APPLE_PAY or GOOGLE_PAY | Cards your cardholder can add to Apple Wallet / Google Wallet. |
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
- Issue directly —
POST /business/card/issuewith the cardholder’s KYC inline. Numero creates (or reuses) the cardholder for you and mints the card. - 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-dev.usenumero.com/numeroaccount/api/v1 |
| Production | https://api.usenumero.com/numeroaccount/api/v1 |
X-Numero-Api-Key header (same as Balance, Transfers, VAS, etc.). Card
endpoints are not signature-gated.
Prerequisites (fund-first + entitlement)
- 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.
- 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).
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 |
Balances are mirrored
Cards are prefunded. Numero mirrors each card’s balance from issuer webhooks and shows you our own number (balance on CardView) — never the issuer’s raw figure. Spend, settlement, refund, reversal,
cross-border and decline events all update the mirror; a reconcile job corrects any drift.
Statuses
Pending → Active → Frozen (reversible) / Terminated (final). Three consecutive
insufficient-balance declines auto-terminate a card (configurable in Watchtower).
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 recoverable processing costs and is auto-debited from your USD card wallet (a deficit is carried if underfunded). View invoices in Dashboard → Cards → Invoices.