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

Balance500,000 naira of play money, resettable
Meterssix reserved numbers, nothing else accepted
Targetssix reserved numbers for airtime, data and cable TV
Providersnothing is contacted
Tokensmade up, prefixed TEST-
Unitsworked out at a flat 70 naira per kWh
Transactionsprefixed TESTSW-
Webhooksyour 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:

Running out of play money

A sandbox order is refused when the balance will not cover it:

422json
{
  "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.

Then

Going live.