Skip to main content
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

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.
Address wallets by their walletReference everywhere below.

List a customer’s wallets

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

Read a wallet’s balance

Scope: customer_wallet:read. Returns the four balances:

Attach a virtual account (receive external money)

Signature required: Yes · Scope: customer_wallet:write The wallet currency determines which bank details you can request. For NGN, verify the customer’s BVN first. For USD or EUR, create a wallet in that currency for the individual customer and call this endpoint with your corporate API key. The customer completes any required steps directly with the verification provider. For USD and EUR, read data.status in the response:

USD or EUR response when the customer needs to take action

A link may be null if that step has already been completed. Treat the links as private. While the request is being processed, both links and account may be null:

Active USD account

Active EUR account

The account details above are examples. Use the paymentRails returned for the issued account. A completed deposit credits the customer’s wallet once, net of applicable fees. Compliance or balance limits can place a credit in pendingBalance for review. External payouts and merchant balance adjustments are unavailable for these USD and EUR receiving accounts. For NGN, repeating the request returns the existing NUBAN. The response includes reference, accountNumber, bankName, and accountName directly under data.

Retire a 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.
Payments sent to a retired NUBAN are still credited to the wallet. Stop sharing the retired account number and provide the customer’s current receiving details. 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

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.
Returns the same shape as attach, carrying the new account number:
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)

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.
Returns the source wallet’s updated balances.

Pay out to a bank

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. Before reserving customer funds, Numero checks that the merchant’s CUSTOMER_POOL has enough settled balance, less active holds, to cover the principal and applicable fees. The customer’s available balance must cover the same total. Pool pending funds are excluded; the separate merchant primary wallet is not automatically used. If the available pool balance is insufficient, the request is rejected before customer funds are reserved. Numero sends a merchant low-balance notification; repeated notices may be limited. Do not depend on notification delivery for transaction state. A timeout is not a confirmed failure: reconcile the payout and webhooks before retrying or releasing funds.

Statement

Scope: customer_wallet:read. Paginated ledger entries — each with postingType, amount, balanceBefore/balanceAfter, narrative, transactionReference, and counterpartyWalletReference for internal transfers.
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.