Skip to main content
Test cards with your test_key_ on the same API base URL. Test cardholders, cards and USD card-wallet funds are isolated from live records, and no real card is issued. See test mode for simulated funding and document requirements.
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 and accept the terms. Access activates immediately when the access fee is zero, or after the configured access fee is debited from your USD card wallet. Insufficient available funds leave access inactive: fund the wallet and retry. If a debit is uncertain, contact support before retrying. Suspended or rejected access needs review.
  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).
A minimum of USD 10 is required to activate a card, including USD 5 mandatory initial funding available to spend. Subsequent funding has a separate configurable fee (currently USD 0.50). See issuance and top-up settlement; do not hard-code these defaults. 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). Repeated explicitly confirmed insufficient-funds declines may trigger a protective freeze. This leaves the card funds in place; it does not permanently close the card.

​
Permanent termination

Card termination is not currently exposed as a public endpoint, in either test or live mode. Freeze is temporary and reversible; it must not be reported as termination or as a return of the card balance.

​
Reveal is sensitive

Ordinary card reads return masked details. Reveal Card Details returns the full PAN, CVV and expiry on explicit request: simulated details with a test key, issuer-backed details with a live key. The request has no body; sign the empty string. Numero does not persist the full PAN/CVV in the card record. Keep keys on your server, display details temporarily to the authorised cardholder, and never log or persist the response.

​
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.