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. WaaS endpoints are additionally scope-gated: your key must carry customers:write, customer_wallet:read, customer_wallet:write, and/or kyc:write as appropriate.
  • 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 envelope: { status, message, code, version, data, error }.

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