Customer Wallets (WaaS)

Each customer can hold one or more wallets. A wallet is usable for internal value the moment it exists — no virtual account required — and gains the ability to receive external money, pay out, and back a card as the customer clears each KYC tier. All amounts are in the wallet’s currency’s major unit (e.g. Naira, not kobo). Every response uses the standard { status, message, code, version, data } envelope.

Create a wallet

POST /api/v1/customers/{customerId}/wallets

Signature required: Yes · Scope: customer_wallet:write · KYC: tier 0 No NUBAN is issued — the wallet works for internal value immediately; attach a virtual account later.

curl -X POST ".../api/v1/customers/4021/wallets" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2" \
  -d '{ "currency": "NGN" }'

{ "status": true, "code": "200", "data": {
  "walletReference": "cw_9f3a…", "customerId": 4021, "currency": "NGN",
  "ledgerBalance": 0, "availableBalance": 0, "pendingBalance": 0, "heldBalance": 0,
  "status": "Active", "virtualAccountNumber": null, "isTest": false, "createdAt": "2026-07-24T09:13:00Z" } }

Address wallets by their walletReference everywhere below.

List a customer’s wallets

GET /api/v1/customers/{customerId}/wallets

Scope: customer_wallet:read. Returns an array of the wallet view above.

Read a wallet’s balance

GET /api/v1/wallets/{walletReference}

Scope: customer_wallet:read. Returns the four balances:

Field	Meaning
`ledgerBalance`	Everything the wallet holds
`availableBalance`	Spendable now (`ledger − held`)
`pendingBalance`	Inbound money awaiting settlement
`heldBalance`	Reserved against in-flight payouts

Attach a virtual account (receive external money)

POST /api/v1/wallets/{walletReference}/virtual-account

Signature required: Yes · Scope: customer_wallet:write · KYC: tier 1 (verified BVN) Assigns a NUBAN so the wallet can receive money from outside Numero. Below tier 1 this returns a 403 telling you to verify the customer’s BVN first.

{ "status": true, "code": "200", "data": {
  "accountNumber": "1234567890", "bankName": "…", "accountName": "Ada Obi" } }

Incoming money lands in pendingBalance and settles to availableBalance. Calling this again on a wallet that already has a NUBAN is idempotent — you get the existing account back rather than a second one being minted and charged for.

Retire a virtual account

DELETE /api/v1/wallets/{walletReference}/virtual-account

Signature required: Yes · Scope: customer_wallet:write Retires the wallet’s active NUBAN. Use this when a customer closes their account or you need to stop advertising a number that has been shared too widely.

This is one-way. There is no un-retire. The only route back to a working NUBAN on this wallet is regenerate, which issues a different account number — the retired one never comes back.

curl -X DELETE ".../api/v1/wallets/cw_9f3a…/virtual-account" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2"

{ "status": true, "code": "200", "data": true }

Money is never lost. A retired NUBAN is a soft decommission: anything that still arrives on it is credited to the wallet as normal, but raises an alert for our operations team — a signal that a payer somewhere is still using a number you have withdrawn. Tell your customers before you retire. Anyone holding the old number — a saved beneficiary, a standing order, an invoice already sent — keeps paying into it, and each of those payments becomes an alert. Returns 400 if the wallet has no active virtual account, so retiring twice is safe rather than silently successful.

Regenerate a virtual account

POST /api/v1/wallets/{walletReference}/virtual-account/regenerate

Signature required: Yes · Scope: customer_wallet:write · KYC: tier 1 (verified BVN) Retires the current NUBAN and attaches a fresh one in a single call. Reach for this when a number has been exposed and you want the customer receiving on a clean one.

The account number changes. Every payer who saved the old NUBAN is now paying a retired account. Treat regeneration as a customer-communication exercise, not just an API call — publish the new number everywhere the old one appears before you regenerate, not after.

curl -X POST ".../api/v1/wallets/cw_9f3a…/virtual-account/regenerate" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2"

Returns the same shape as attach, carrying the new account number:

{ "status": true, "code": "200", "data": {
  "accountNumber": "0987654321", "bankName": "…", "accountName": "Ada Obi" } }

Safe on a wallet that has no virtual account yet — the retire step is skipped and you simply get a new NUBAN. The customer must still be at KYC tier 1, exactly as for attach.

Transfer between wallets (internal, instant)

POST /api/v1/wallets/{walletReference}/transfer

Signature required: Yes · Scope: customer_wallet:write · Idempotency-Key: required Moves money to another wallet of the same merchant and currency. Pure sub-ledger move — instant, no external rail.

curl -X POST ".../api/v1/wallets/cw_9f3a…/transfer" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "toWalletReference": "cw_7b1c…", "amount": 2500, "narrative": "split" }'

Returns the source wallet’s updated balances.

Pay out to a bank

POST /api/v1/wallets/{walletReference}/payout

Signature required: Yes · Scope: customer_wallet:write · Idempotency-Key: required · KYC: tier 2 (fully identified) Sends money to an external bank account. Funds are reserved immediately; the payout returns in Held and settles when the bank transfer completes. Bounded by the customer’s per-tier velocity limits.

curl -X POST ".../api/v1/wallets/cw_9f3a…/payout" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amount": 5000, "destinationAccountNumber": "0123456789",
        "destinationBankCode": "058", "destinationAccountName": "Ada Obi", "narrative": "payout" }'

{ "status": true, "code": "200", "data": {
  "payoutReference": "po_2f8b…", "walletReference": "cw_9f3a…",
  "amount": 5000, "fee": 10, "currency": "NGN",
  "destinationAccountNumber": "0123456789", "destinationBankCode": "058",
  "status": "Held", "walletAvailableBalance": 12490, "createdAt": "2026-07-24T09:20:00Z" } }

Statement

GET /api/v1/wallets/{walletReference}/transactions?pageNumber=1&pageSize=50

Scope: customer_wallet:read. Paginated ledger entries — each with postingType, amount, balanceBefore/balanceAfter, narrative, transactionReference, and counterpartyWalletReference for internal transfers.

Link a card

POST /api/v1/wallets/{walletReference}/link-card

Signature required: Yes · Scope: customer_wallet:write · KYC: tier 2 Links the wallet to the customer’s card profile so an issued card draws from the wallet balance. Because a card is external spending, it carries the same tier bar as a payout.

Getting Started

Transfers & Payouts

Collections (Virtual Accounts)

Wallet-as-a-Service

Customers

Invoices

Cards

Cardholders

Balance & Transactions

Value Added Services

Credit

Verification / KYC

Webhooks

Customer Wallets (WaaS)

Create a wallet

List a customer’s wallets

Read a wallet’s balance

Attach a virtual account (receive external money)

Retire a virtual account

Regenerate a virtual account

Transfer between wallets (internal, instant)

Pay out to a bank

Statement

Link a card

​Create a wallet

​List a customer’s wallets

​Read a wallet’s balance

​Attach a virtual account (receive external money)

​Retire a virtual account

​Regenerate a virtual account

​Transfer between wallets (internal, instant)

​Pay out to a bank

​Statement

​Link a card

Create a wallet

List a customer’s wallets

Read a wallet’s balance

Attach a virtual account (receive external money)

Retire a virtual account

Regenerate a virtual account

Transfer between wallets (internal, instant)

Pay out to a bank

Statement

Link a card