So the switch from testing to going live is: change the key. Nothing else.
What test mode gives you
- Simulated providers — transfers, collections and card calls resolve against simulators, so nothing leaves your account.
- An isolated test wallet — separate from your live balance. Your live money is never read or moved in test mode.
- Mode-aware webhooks — test events are delivered only to webhook subscriptions registered as test, and carry
livemode: false. - Separate operational records — customers, WAAS wallets, virtual accounts, invoices, verification history and cards are isolated by mode. A reference from one mode cannot be used to access the other. Customer external IDs can be reused independently in test and live.
- Mode-preserving background processing — queued test transfers, bill payments and verifications remain simulated when a worker processes them later. Pending is not proof of completion; poll the reference or handle the appropriate test webhook.
- No real invoice emails — test invoice creation and cancellation are available through the API, but test invoices do not send payer emails or open a live hosted payment page. Use fictional customer details.
The sandbox endpoints below require a
test_key_. Calling them with a live key returns a clear rejection — they can never touch live balances.Test data
Virtual-card accounting
Use yourtest_key_ on the same base URL for card and cardholder endpoints. Test
cardholders, cards, balances and transaction history are separate from live records;
a live card or cardholder reference cannot be used in test mode, or vice versa.
Your test USD card wallet starts with USD 1,000 of simulated funds, provisioned
once. Reading it or issuing another request does not replenish it. Available card
products can be tested without activating live card access.
Test cards use the same public request/response models and
business validation as live cards, with simulated provider calls. A minimum of USD 10
is required to activate a card, including USD 5 mandatory initial funding available
to spend. Read the available products and applicable pricing before issuing a card.
Supply fictional identity details and a valid public HTTPS document URL. In test-key
mode, the URL is validated but its contents are not downloaded; only synthetic
image evidence is used by the simulator. Live requests require genuine documents.
A successful USD 1 top-up adds exactly USD 1 (USD 5 → USD 6). The current default
funding fee is USD 0.50 additional to the principal. Negative/zero amounts and withdrawals
above the card balance fail without changing the simulated balance. State is persisted
across sandbox restarts. Real provider calls and live wallet movements never occur.
Default simulation settles synchronously; production may return Pending/Review and
complete later. Never use HTTP 200 alone as confirmation. An unresolved operation
must be reconciled before retrying; do not assume that a timeout means failure.
Use the webhook test-event endpoint below to test delivery separately; a synthetic event
does not itself prove or perform a financial settlement.
Test mode is deterministic: the input you send decides the outcome. No special headers, no dashboard toggles —
send one of the values below and you get that result, every time. For a simulated operation, any input value not
listed here takes the happy path, so the success case needs no magic values.
That applies to the values you send, not to every endpoint. An operation Numero does not yet simulate returns
HTTP 501 naming the gap, rather than a fabricated success — so a green test run means the call was actually
exercised, not merely that nothing objected. If you hit a 501, tell us; it is a missing simulation, not your bug.
Verification & credit — the BVN decides
11111111111 is the one worth testing against. The fields are present and null — a bureau returning “we hold
no score for this person” is an answer, not an error, and your code has to survive it. See
Reading normalizedResult.
What you get back. These are the real responses, not illustrations — POST /business/verification/credit-score:
Note the middle row: a thin file is a successful, billable verification whose answer happens to be “no score”.
Branch on the field being
null, not on success. Full bodies for all three are on the
Credit page.
Test mode mirrors what each product really returns — including that
credit-first-central returns no score.
If you need a number to derive a lending band, use credit-score or credit-summary. We’d rather the sandbox
tell you that now than have you discover it in production.Transfers & payouts — the amount decides
Account validation (name enquiry)
Bills & airtime
Fund your test wallet
Top up your test balance with simulated money.{ "amount": 100, "currency": "USD" } to the same endpoint using your test key and normal request signature. Its balance cap is USD 10,000. The dashboard’s Fund test wallet control also lets you select NGN or USD. No live wallet or real provider balance is funded.
Reset your sandbox
Wipe your test transactions and virtual accounts and reset the test balance to its default.Test transactions are capped at 30 per merchant — the oldest are pruned automatically. Reset whenever you want a clean slate.
Fire a test webhook
Send a sample event to your registered test webhook endpoint(s) to exercise your handler without waiting for a real payment.livemode: false.
Going live
- Build and verify everything with your
test_key_. - Swap in your
live_key_— same base URL, same endpoints. - Register your live webhook URL and confirm you’re handling
livemode: truedeliveries.