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.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
- 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):
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)
- Product access — your business must be approved for the requested card product. Check the entitlement returned by the products endpoint.
- Available balance — card issuance and funding debit your USD card wallet. Check its available balance before submitting a request.
approval_required.
Endpoints
Card balances
Cards are prefunded: a card’sbalance 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. 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. Any unpaid amount remains due.