Sandbox
A test key, play money, and six numbers that behave predictably.
Test mode is a full copy of the API that contacts no provider and spends no real money. Build against it until your integration is boring, then swap the key.
Getting in
Issue a key in test mode on the API keys page. That is all.
There is no header, no flag and no separate hostname: the key decides the mode.
Confirm with Get account, which reports
mode: "test" and your sandbox_balance.
Test keys do not need KYB approval and are not checked against your address allowlist, so they work from your laptop.
What you get
| Balance | 500,000 naira of play money, resettable |
| Meters | six reserved numbers, nothing else accepted |
| Targets | six reserved numbers for airtime, data and cable TV |
| Providers | nothing is contacted |
| Tokens | made up, prefixed TEST- |
| Units | worked out at a flat 70 naira per kWh |
| Transactions | prefixed TESTSW- |
| Webhooks | your test URL, signed with your test secret |
Nothing in test mode touches a wallet, appears in any financial report, or reaches a real customer.
What is identical
The request and response shapes, the envelope, the status codes, the idempotency behaviour, the concurrency accounting, the webhook signature scheme and the catalogue. That is the point: when you go live, only the credential changes.
Validation is identical too. A sandbox order still needs a non-empty
disco_code, an amount above zero, and a valid access_code from meter
verify. The sandbox will not let you skip steps that live mode requires.
The reserved numbers
Any other meter or target is refused with "This is not one of the sandbox test meters." Full tables, with what each one does:
- Reserved meters for electricity
- Reserved targets for airtime, data and cable TV
Running out of play money
A sandbox order is refused when the balance will not cover it:
{
"success": false,
"status": "failed",
"code": 422,
"message": "Your sandbox balance will not cover this order. Reset it from your dashboard to carry on testing.",
"data": null
}Reset it from your dashboard, on the overview page. The balance goes back to 500,000 and your claimed references are untouched, so pick a fresh reference after a reset rather than reusing one.
Tip
Testing the empty-balance path on purpose is worth ten minutes. Spend the
balance down with a few large orders and watch what your code does with that
422. It is the same shape your live integration will meet the first time a
partner balance runs dry, which happens on a Friday afternoon.
What the sandbox cannot show you
- Real provider behaviour. Live providers are slower, occasionally refuse things the sandbox accepts, and return payloads that differ by disco. Live meter verify passes the provider's own response through unchanged, so expect fields the sandbox never shows you.
- Real prices. The sandbox tariff is a flat 70 naira per kWh and is not the live tariff, deliberately: a real figure here would have you building expectations on a number that then changes.
- Real commission. Sandbox orders earn nothing.
- Real timing. Two reserved numbers delay by 15 seconds, which is the only latency you will see. Live orders vary.