Home · Developers
User acceptance script
The acceptance run an agency completes in the sandbox before a live key is issued. Name your agency to get the script with its code filled in.
Which agency is this for?
Before you start
- A sandbox key for your agency, with the scopes your integration needs.
- Base URL https://services.abiastate.gov.ng/api/v1, reachable from the server that will run in production — not from a laptop.
- A fresh sandbox: call POST /sandbox/reset first, so the identities are exactly as published.
- Somewhere to record, for every case, the X-Request-Id and the verification_id. That is the evidence BIR signs off against.
UAT-1
The key works and is scoped
GET /ping
- Call with your sandbox key.
- Read env, scopes and rate_per_minute.
Pass when: ok=true, env="sandbox", and scopes contains every scope your integration needs. A verification id is present.
| Run at | X-Request-Id | verification_id | Result |
|---|---|---|---|
UAT-2
A compliant taxpayer verifies
POST /parties/verify {"abssin":"SBX0000101"}
- Verify the compliant company.
- Read data.compliant and data.party.tax_clearance.
Pass when: ok=true, data.compliant=true, data.reason_codes is empty, data.party.tax_clearance.held=true, and every entry in data.party.directors has tcc_held=true.
| Run at | X-Request-Id | verification_id | Result |
|---|---|---|---|
UAT-3
A non-compliant party is refused with a reason and a link
POST /transactions with party SBX0000102
- Submit a transaction for the company whose director is not compliant.
- Open the remediation link in a browser.
Pass when: ok=false, error.code="DIRECTOR_NONCOMPLIANT", the failing director is named in the message, error.remediation_url opens a working page, and data.transaction_ref is present. (BRD acceptance 1 and 7.)
| Run at | X-Request-Id | verification_id | Result |
|---|---|---|---|
UAT-4
An unregistered person is identified as such
POST /parties/verify {"nin":"99900000001"}
- Verify a national identity number that carries no ABSSIN.
- Read data.reason_codes and data.remediation_url.
Pass when: ok=true — the question was answered — with data.compliant=false, PARTY_NO_ABSSIN in data.reason_codes and data.remediation_url pointing at registration. Submit the same person on POST /transactions and THAT is refused, ok=false with PARTY_NO_ABSSIN: the refusal happens where a decision is asked for, never on a lookup.
| Run at | X-Request-Id | verification_id | Result |
|---|---|---|---|
UAT-5
Value above the clearance basis raises an assessment
POST /transactions with declared_value above the basis
- Submit process LND/COFO for SBX0000101 with a declared value of 25,000,000.
- Read data.assessments.
Pass when: An assessment is returned with a bill reference and a frozen basis sentence, and the capital gains gate reads ASSESSED rather than CLEARED. pay_url is null in the sandbox, which has no gateway — POST /sandbox/pay is the stand-in. (BRD acceptance 5.)
| Run at | X-Request-Id | verification_id | Result |
|---|---|---|---|
UAT-6
Payment clears the gate
POST /sandbox/pay then POST /transactions/{ref}/payments
- POST /sandbox/pay with the bill reference from UAT-5.
- Cite the returned data.paid_ref on POST /transactions/{ref}/payments as {"reference":"…","head":"CGT"}.
Pass when: data.matched=true and, in data.transaction, the gate that was ASSESSED now reads CLEARED and the transaction status becomes "eligible". (BRD acceptance 2 and 6.)
| Run at | X-Request-Id | verification_id | Result |
|---|---|---|---|
UAT-7
The document issues and verifies publicly
POST /transactions/{ref}/document then GET /public/documents/{no}
- Issue the document.
- Open data.document.verify_url in a browser and call the public endpoint with data.document.short_number.
Pass when: data.document.document_number ends in the clearance reference, and the public answer names the issuing agency and the holder with data.document.status="valid". A sandbox document also carries sandbox=true — it is a rehearsal, never a state document. (BRD acceptance 3 and 4.)
| Run at | X-Request-Id | verification_id | Result |
|---|---|---|---|
UAT-8
A retry cannot double-issue
Repeat any POST with the same Idempotency-Key
- Repeat the issuance call with the identical key and body.
- Compare the two responses.
Pass when: The second response is byte-identical, carries Idempotent-Replayed: true, and no second document number exists. Then repeat with the same key and a DIFFERENT body: IDEMPOTENCY_KEY_REUSED.
| Run at | X-Request-Id | verification_id | Result |
|---|---|---|---|
What the run proves
Each proof is one of the acceptance criteria the platform was built against. A run that passes every case has demonstrated all five.
| Proof | Shown by | Criterion |
|---|---|---|
| Nothing issues to a non-compliant taxpayer | UAT-3 refuses with a named reason code and a link that works; UAT-6 shows the same case clearing once regularised. | Acceptance 1 and 2 |
| The document carries its compliance | UAT-7: the number embeds the clearance reference, and the public page shows the same holder, agency and status. | Acceptance 3 and 4 |
| Money owed is computed, not negotiated | UAT-5 and UAT-6: a declared value above the basis of the clearance held raises an additional assessment with a frozen basis sentence, and settling it clears the gate. | Acceptance 5 and 6 |
| A company is only as compliant as its directors | UAT-3 names the individual director who fails, not the company in general. | Acceptance 7 |
| The API journey is the console journey | UAT-2 to UAT-7 run end to end with a verification id on every answer; the same case worked in the console reaches the same document. | Acceptance 8 |
Sign-off
Print this page, attach the recorded ids, and have both parties sign. BIR records the result against your agency's integration and issues the live key against the same scopes the sandbox key carried.
| Party | Name | Role | Signature | Date |
|---|---|---|---|---|
| your agency | ||||
| Vendor / integrator | ||||
| Board of Internal Revenue |
A case that cannot pass is not a reason to issue a live key with a note attached. Fix it, rerun the case, and record the new ids.