Sandbox
Sandbox keys answer from a seeded parallel register: no shared taxpayer table, no collection ledger, no SMS, no email — and a nightly reset that puts the identities back exactly as documented.
What the sandbox is
The same code, the same rules and the same envelope, answering from a seeded parallel register. A key beginning ak_sbx_ puts every read and every write in the sandbox environment; there is no flag in the request that can move it, and no live key that can reach sandbox data.
- The shared taxpayer registers are never read and never written.
- Nothing reaches the collection ledger, so sandbox activity cannot move a revenue figure by one naira.
- No SMS, no email, no upstream identity call leaves the platform.
- Documents issued in the sandbox are watermarked and verify publicly as sandbox — they read as a test, never as a state document.
The identities
Deterministic, and restored by every reset. Build your test cases on these rather than on something you created yesterday.
| Identifier | Kind | State | What it is for |
|---|---|---|---|
| SBX0000001 | Individual | Compliant | Current tax clearance for the running year. The happy path. |
| SBX0000002 | Individual | Expired | Clearance expired last year — expect TCC_STALE_FOR_YEAR or TCC_EXPIRED with a remediation link. |
| SBX0000101 | Limited company | Compliant | Company and every director current. VAT registered, so VAT is withheld on its vouchers (BR-16). |
| SBX0000102 | Limited company | Blocked | One director is not compliant — expect DIRECTOR_NONCOMPLIANT naming SBX0000013 (BR-10, acceptance 7). |
| SBX0000013 | Individual | Blocked | The failing director of SBX0000102. Holds no clearance at all. |
| SBX0000201 | Business name | Compliant | Sole proprietorship — the proprietor is checked, not directors (BR-11). |
| 99900000001 | NIN, no ABSSIN | Unregistered | A person the register does not hold — expect PARTY_NO_ABSSIN, then register and retry. |
The process
- Code
- LND/COFO
- Issues
- Certificate of Occupancy (sandbox)
- Note
- Send it as LND/COFO or as the bare code COFO — anything before the last slash is discarded. Every agency holding a sandbox key gets its own copy of this process, because a transaction is refused unless its process belongs to the calling agency. Value-bearing: a declared_value drives the capital gains gate, and a value above the clearance basis raises an automatic additional assessment (acceptance 5).
Paying, in a world with no money
There is no gateway in the sandbox. POST /sandbox/pay is the stand-in for a taxpayer paying a bill: it settles the bill so the gate waiting on it can clear.
curl -s https://services.abiastate.gov.ng/api/v1/sandbox/pay \
-H 'Authorization: Bearer ak_sbx_4K21PQ7M.0tS3-…' \
-H 'Idempotency-Key: pay-lands-00821' \
-H 'Content-Type: application/json' \
-d '{"reference":"SBX-BAS-000418"}' It settles the assessment in full and hands back a paid_ref — that is the reference you cite on POST /transactions/{ref}/payments. There is no partial-payment parameter: to see a shortfall, declare a value above the basis of the clearance held and let the platform raise the balance assessment itself.
Resetting
The sandbox reseeds itself nightly, and you can reseed it yourself up to three times an hour. The transactions, documents, contracts and vouchers the fixtures took part in go; the published ABSSINs themselves survive, because they are documented and your stored test data points at them.
curl -s -X POST https://services.abiastate.gov.ng/api/v1/sandbox/reset \ -H 'Authorization: Bearer ak_sbx_4K21PQ7M.0tS3-…' \ -H 'Idempotency-Key: reset-2026-09-14-1'
Subscribe to sandbox.reset if your test harness caches references — it is the warning that they have just stopped existing.
Before you ask for a live key
Run the UAT script end to end and keep the request ids. That evidence is what BIR signs off against.
Open the UAT script