Skip to main content
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. 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): 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.

​
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

​
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 and take funds back with 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.