Skip to main content
Wallet-as-a-Service (WaaS) lets you build wallets for your own end-users on top of Numero. You create a customer, give the customer one or more wallets, and — as the customer clears each KYC step — attach a virtual account so the wallet can receive external money, move money between wallets, pay out to banks, and link a card. There is one customer model across the whole platform. The same customer you create here is the customer you attach a card to — you do not create the customer twice.

​
The three objects

A wallet holds four balances, always returned together:
Wallet balances are a strictly-maintained sub-ledger of your merchant pooled wallet. A customer wallet can never spend another customer’s balance — every debit is guarded against that wallet’s own available balance.

​
The KYC ladder

Capabilities unlock as the customer verifies more. You never provide more than a step needs — a wallet that only holds value asks for nothing but a name. This is the default ladder; the requirements and per-tier limits are configurable by your Numero admin, so what a given tier unlocks (and its transaction limits) may differ for your account. This reflects CBN’s identity requirements — full identity for moving money out is BVN and NIN and a government ID. Each item is a real, billable verification Numero performs; a tier only rises when the check genuinely passes. Each endpoint below states the tier it requires. Calling an endpoint above the customer’s current tier returns a clear 403 telling you which step is missing — never a silent failure.

​
A typical integration

​
Base URL, auth, and test mode

  • Base URL: https://api.usenumero.com/numeroaccount
  • Auth: every request sends X-Numero-Api-Key. Money-moving POSTs also require a request signature — see Request Signing. All authenticated merchants receive customers:write, customer_wallet:read, customer_wallet:write, and kyc:write by default, for both test and live keys, including existing merchants. No manual WaaS activation is required. Customer ownership, KYC tiers, wallet limits and available-balance checks still apply. Virtual-card approval remains separate; unrelated API scopes are not granted by this default.
  • Test mode: send a test_key_… key and everything below runs against simulated providers on an isolated test wallet — same base URL, same endpoints, live balances never touched. See Test Mode.
Every response uses the standard public envelope: { data, error, meta }.

​
Customer availability versus pool settlement

Normal virtual-account inflows credit the customer’s wallet immediately, net of the configured collection fee. The merchant pool may retain that incoming amount in its own pending settlement balance. Customer compliance or tier-limit breaches can still hold funds for review. External payouts require both the customer’s available balance and sufficient settled funds in the merchant’s CUSTOMER_POOL, including fees and after active holds. Pending provider settlements cannot fund payouts. Funds in the merchant’s separate primary wallet are not automatically drawn into the pool. Reconciliation compares total pool assets (balance plus pending) with total customer claims (ledger balances plus pending). Different settlement buckets alone are not a missing-credit discrepancy. Later provider settlement must not credit the customer again.

​
Webhooks

Numero emits an event to your configured webhook endpoint for every wallet action, so you don’t have to poll. Each event body is { "event": "<name>", "data": { … } }, where data is the same shape as the corresponding API response. A payout returns immediately in Held/pending; the payout.sent or payout.failed event tells you the final outcome once the bank transfer resolves.