{ "openapi": "3.0.3", "info": { "title": "Abia State Government Services Platform API", "version": "1.0.0", "description": "The machine interface of the Abia State Board of Internal Revenue compliance platform. An agency system verifies a taxpayer, submits a transaction, cites payments, issues a final document, onboards contractors and raises payment vouchers through the same services the officer consoles use. Every answer carries a verification id; every refusal names a published reason code.", "contact": { "name": "BIR integration desk", "email": "support@abiaone.xyz" } }, "servers": [ { "url": "https://services.abiastate.gov.ng/api/v1", "description": "Live and sandbox share one base URL; the key decides the environment." } ], "tags": [ { "name": "Connectivity", "description": "Prove a key before anything real." }, { "name": "Parties", "description": "Who the taxpayer is and whether they are compliant." }, { "name": "Transactions", "description": "A case through the compliance gates, from submission to issuance." }, { "name": "Documents", "description": "Final documents, their evidence, and public verification." }, { "name": "Contractors", "description": "Contractor onboarding for award and payment (FR-6)." }, { "name": "Contracts", "description": "Award requests, the award gate and the contracts register." }, { "name": "Vouchers", "description": "Payment vouchers and deduction at source (FR-7)." }, { "name": "Payments", "description": "Telling the platform money was collected against an answer it gave." }, { "name": "Webhooks", "description": "Subscriptions to platform events." }, { "name": "Sandbox", "description": "Sandbox-only helpers. A live key is refused." }, { "name": "Queue", "description": "Requests accepted in degraded mode, and what became of them." }, { "name": "Warehouse", "description": "The nightly anonymised data-warehouse extracts. Live keys with the dw scope only." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/contractors": { "post": { "operationId": "onboardContractor", "summary": "Onboard a contractor", "description": "Registers a contractor for award and payment (FR-6.1). The entity and every director are checked against the clearance registry and that answer is frozen into the record with its verification ids, so a later dispute can see what was known on the day. Bank details are encrypted at rest and only the last four digits are ever returned.\n\n- The record lands pending_verification. A second officer verifies it in the procurement console, and the officer who onboarded may never be the officer who verifies (SEC-8) — which is why there is no verify endpoint here.\n\n- Changing bank details bumps a version; a voucher pins the version it was approved against.\n\n- Identifier and bank fields sit at the TOP LEVEL of the body. There is no nested party or bank object.\n\n- This endpoint is part of the procurement surface. When that surface is switched off on a deployment every call here answers API_DISABLED.\n\nScope: `transact`.\n\nReason codes: PARTY_NOT_FOUND, PARTY_NO_ABSSIN, BR_MISSING, DIRECTOR_NONCOMPLIANT, PROPRIETOR_NONCOMPLIANT, TCC_MISSING, VALIDATION_ERROR, API_DISABLED.", "tags": [ "Contractors" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "abssin": { "type": "string", "description": "One identifier is required: abssin, nin, rc_number, tin or party_ref." }, "rc_number": { "type": "string", "description": "CAC registration number. Doubles as the identifier when no other is sent.", "example": "RC9900101" }, "tin": { "type": "string", "description": "TIN." }, "party_ref": { "type": "string", "description": "A party reference already issued." }, "identifier_kind": { "type": "string", "description": "The explicit form: name the kind here and put the value in `identifier`.", "enum": [ "abssin", "nin", "rc", "tin", "party_ref" ] }, "identifier": { "type": "string", "description": "The identifier, when identifier_kind is given." }, "legal_name": { "type": "string", "description": "Name as registered, at most 200 characters.", "example": "Sandbox Compliant Holdings Limited" }, "entity_type": { "type": "string", "description": "Decides which deductions apply later (BR-15, BR-16). Defaults to llc.", "enum": [ "individual", "business_name", "llc", "other" ] }, "vat_registered": { "type": "boolean", "description": "VAT is withheld only from a registered limited company (BR-16)." }, "vat_reg_no": { "type": "string", "description": "VAT registration number." }, "classes_of_work": { "type": "array", "items": { "type": "string" }, "description": "What this contractor is registered to do." }, "bank_code": { "type": "string", "description": "Bank code.", "example": "058" }, "account_no": { "type": "string", "description": "Account number. Encrypted on receipt, never logged and never returned — not even to the agency that sent it." }, "account_name": { "type": "string", "description": "Account name as held by the bank." } }, "required": [ "legal_name", "entity_type", "bank_code", "account_no", "account_name" ], "example": { "rc_number": "RC9900101", "legal_name": "Sandbox Compliant Holdings Limited", "entity_type": "llc", "vat_registered": true, "classes_of_work": [ "civil" ], "bank_code": "058", "account_no": "0123456789", "account_name": "Sandbox Compliant Holdings Limited" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "contractor": { "type": "object", "properties": { "contractor_ref": { "type": "string", "description": "CTR-YYYY-XXXXXX." }, "legal_name": { "type": "string", "description": "As registered." }, "entity_type": { "type": "string", "description": "As registered." }, "abssin": { "type": "string", "description": "State identification number.", "nullable": true }, "rc_number": { "type": "string", "description": "CAC number.", "nullable": true }, "tin": { "type": "string", "description": "TIN.", "nullable": true }, "vat_registered": { "type": "boolean", "description": "As registered." }, "vat_reg_no": { "type": "string", "description": "As registered.", "nullable": true }, "classes_of_work": { "type": "array", "items": { "type": "string" }, "description": "As registered." }, "status": { "type": "string", "description": "Only an active contractor may be awarded.", "enum": [ "draft", "pending_verification", "active", "suspended" ] }, "bank": { "type": "object", "properties": { "bank_code": { "type": "string", "description": "As supplied.", "nullable": true }, "account_name": { "type": "string", "description": "As supplied.", "nullable": true }, "account_last4": { "type": "string", "description": "The last four digits, and nothing more.", "nullable": true }, "version": { "type": "integer", "description": "Bumped on every bank change; a voucher pins the version it was approved against." }, "verified_at": { "type": "string", "description": "When the account was verified.", "nullable": true } }, "required": [ "version" ], "description": "Never the account number." }, "directors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Director name." }, "role": { "type": "string", "description": "director, proprietor or signatory." }, "tcc_status": { "type": "string", "description": "What the registry said on the day.", "nullable": true }, "tcc_ref": { "type": "string", "description": "Their certificate reference.", "nullable": true }, "verification_id": { "type": "string", "description": "The ledger id for that check.", "nullable": true } }, "required": [ "name", "role" ] }, "description": "The snapshot frozen at onboarding." }, "verified_at": { "type": "string", "description": "When a second officer verified the record.", "nullable": true }, "created_at": { "type": "string", "description": "When it was onboarded.", "nullable": true } }, "required": [ "contractor_ref", "legal_name", "entity_type", "vat_registered", "classes_of_work", "status", "bank", "directors" ], "description": "The record as held." }, "compliance": { "type": "object", "properties": { "favourable": { "type": "boolean", "description": "Whether entity and directors all cleared on the day." }, "reason_code": { "type": "string", "description": "The code, when they did not.", "nullable": true }, "verification_id": { "type": "string", "description": "The ledger id for the entity check.", "nullable": true }, "tcc_ref": { "type": "string", "description": "The entity certificate cited.", "nullable": true }, "directors": { "type": "array", "items": { "type": "object" }, "description": "Per director: name, role, tcc_status, tcc_ref, valid_until." } }, "required": [ "favourable", "directors" ], "description": "The frozen clearance answer.", "nullable": true }, "message": { "type": "string", "description": "What happens next, in a sentence." } }, "required": [ "contractor", "message" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/contractors/{ref}": { "get": { "operationId": "getContractor", "summary": "Read a contractor", "description": "The record as held, including the frozen director snapshot and the bank details reduced to their last four digits.\n\n- The account number is not in this answer and will not be added to it: an API that can echo an account number is an API that can be used to harvest them.\n\nScope: `transact`.\n\nReason codes: NOT_FOUND, SCOPE_MISSING, API_DISABLED.", "tags": [ "Contractors" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "Contractor reference, CTR-YYYY-XXXXXX.", "schema": { "type": "string", "example": "CTR-2026-000318" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "contractor": { "type": "object", "description": "As POST /contractors returns it." } }, "required": [ "contractor" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/contracts": { "post": { "operationId": "requestContract", "summary": "Request a contract award and run the award gate", "description": "Creates the contract and runs the award gate with the contract sum as the declared value. Stamp duty is due ON AWARD (BR-12), so the answer carries the stamp bill and what is outstanding on it; capital gains is recorded cleared with a reference or not applicable with a named reason (BR-23). The award itself is taken by a Due Process officer in the console once the gates are terminal — there is no force path, and no API path to an unearned award.\n\n- The award number IS the final document number. There is no separate certificate to issue.\n\n- Blocking gates are the EXPECTED answer here, not a refusal: ok=true with may_be_awarded=false and the outstanding stamp duty named. BR-12 means the duty has not been paid yet by definition.\n\nScope: `transact`.\n\nReason codes: NOT_FOUND, VALIDATION_ERROR, SCOPE_MISSING, API_DISABLED.", "tags": [ "Contracts" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contractor_ref": { "type": "string", "description": "An active contractor, CTR-YYYY-XXXXXX.", "example": "CTR-2026-000318" }, "title": { "type": "string", "description": "What the contract is for, at most 255 characters.", "example": "Reconstruction of Bende Road, Phase 2" }, "description": { "type": "string", "description": "Scope in words." }, "contract_type": { "type": "string", "description": "Doubles as the withholding service class (BR-15). Defaults to construction.", "enum": [ "construction", "supply", "consultancy", "services", "rent", "other" ] }, "contract_sum": { "type": "number", "description": "Award value in naira, greater than zero.", "example": 184500000 }, "vat_treatment": { "type": "string", "description": "How VAT sits in the sum; it decides the withholding base later. Defaults to exclusive.", "enum": [ "inclusive", "exclusive", "none" ] }, "retention_pct": { "type": "number", "description": "Retention percentage held from each payment, 0 to 100." }, "procurement_method": { "type": "string", "description": "Open competitive, selective, direct or emergency." }, "due_process_ref": { "type": "string", "description": "The Bureau reference for the procurement." }, "start_date": { "type": "string", "description": "YYYY-MM-DD." }, "end_date": { "type": "string", "description": "YYYY-MM-DD." } }, "required": [ "contractor_ref", "title", "contract_type", "contract_sum" ], "example": { "contractor_ref": "CTR-2026-000318", "title": "Reconstruction of Bende Road, Phase 2", "contract_type": "construction", "contract_sum": 184500000, "vat_treatment": "exclusive", "retention_pct": 5 } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "contract": { "type": "object", "description": "The contract as raised — the same shape GET /contracts/{ref} returns." }, "may_be_awarded": { "type": "boolean", "description": "True when every award gate is terminal and a Due Process officer can sign." }, "blocking": { "type": "array", "items": { "type": "object" }, "description": "Gate, reason code, subject, amount due and a readable message for each." }, "reason_codes": { "type": "array", "items": { "type": "string" }, "description": "The distinct codes standing in the way." }, "remediation_url": { "type": "string", "description": "Where the contractor regularises.", "nullable": true }, "message": { "type": "string", "description": "What happens next, in a sentence." } }, "required": [ "contract", "may_be_awarded", "blocking", "reason_codes", "message" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/contracts/lookup": { "post": { "operationId": "lookupContract", "summary": "Call a contract up by its full award number", "description": "The award number is a final document number and contains forward slashes, so the long form travels in the body. This is the call the voucher screen makes: it returns the award date, the sum, approved variations, paid to date, retention and the stamp and capital gains position — everything needed to raise a payment, and no bank details.\n\n- Nothing is minted, so no Idempotency-Key is required.\n\nScope: `transact`.\n\nReason codes: CONTRACT_NOT_FOUND, VALIDATION_ERROR, SCOPE_MISSING, API_DISABLED.", "tags": [ "Contracts" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "final_doc_no": { "type": "string", "description": "The award number, long or short. award_number and number are accepted as synonyms.", "example": "AB/DPO/AWRD/2026/9K41XA/TCC-2026-004418" }, "contract_ref": { "type": "string", "description": "The contract reference, CON-YYYY-XXXXXX, when you hold that instead. One of the two is required." } }, "example": { "final_doc_no": "AB-DPO26-9K41XA" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "contract": { "type": "object", "description": "As GET /contracts/{ref}." } }, "required": [ "contract" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/contracts/{ref}": { "get": { "operationId": "getContract", "summary": "Read a contract by its contract reference", "description": "Everything a paying agency needs before raising a voucher: award date, sum, approved variations, paid to date, retention held and released, the stamp and capital gains position, and the contractor it was awarded to.\n\n- {ref} is the CONTRACT reference, CON-YYYY-XXXXXX — the award number is not accepted in a path, in either form. Post the award number to /contracts/lookup instead.\n\nScope: `transact`.\n\nReason codes: CONTRACT_NOT_FOUND, SCOPE_MISSING, API_DISABLED.", "tags": [ "Contracts" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "Contract reference, CON-YYYY-XXXXXX.", "schema": { "type": "string", "example": "CON-2026-000318" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "contract": { "type": "object", "properties": { "contract_ref": { "type": "string", "description": "CON-YYYY-XXXXXX." }, "award_number": { "type": "string", "description": "The final document number. Null until awarded.", "nullable": true }, "status": { "type": "string", "description": "requested, draft, gated, awarded, active, completed, terminated or void." }, "mda": { "type": "string", "description": "The awarding agency." }, "contractor": { "type": "object", "description": "contractor_ref, legal_name, entity_type, abssin and status. No bank details.", "nullable": true }, "title": { "type": "string", "description": "What the contract is for." }, "contract_type": { "type": "string", "description": "The withholding service class." }, "vat_treatment": { "type": "string", "description": "How VAT sits in the sum." }, "due_process_ref": { "type": "string", "description": "Bureau reference.", "nullable": true }, "procurement_method": { "type": "string", "description": "How it was procured.", "nullable": true }, "contract_sum": { "type": "number", "description": "Award value." }, "approved_variations": { "type": "number", "description": "Total approved variations, each stamped on its increment." }, "contract_value": { "type": "number", "description": "Sum plus approved variations — the ceiling cumulative voucher gross is checked against." }, "gross_paid": { "type": "number", "description": "Sum of paid vouchers." }, "unpaid_balance": { "type": "number", "description": "contract_value less gross_paid." }, "retention": { "type": "object", "description": "pct, held, released." }, "award_date": { "type": "string", "description": "YYYY-MM-DD.", "nullable": true }, "start_date": { "type": "string", "description": "YYYY-MM-DD.", "nullable": true }, "end_date": { "type": "string", "description": "YYYY-MM-DD.", "nullable": true }, "stamp_duty": { "type": "object", "description": "status (pending, assessed, paid, not_applicable), amount, bill_ref, payment_ref." }, "cgt": { "type": "object", "description": "status (pending, cleared, not_applicable), na_reason, reference." }, "tax_clearance": { "type": "object", "description": "reference and verification_id of the clearance the award was judged against." }, "gate_transaction_ref": { "type": "string", "description": "The transaction the award gate ran on.", "nullable": true }, "created_at": { "type": "string", "description": "When it was raised.", "nullable": true } }, "required": [ "contract_ref", "status", "mda", "title", "contract_type", "vat_treatment", "contract_sum", "approved_variations", "contract_value", "gross_paid", "unpaid_balance", "retention", "stamp_duty", "cgt", "tax_clearance" ], "description": "The contract." } }, "required": [ "contract" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/contracts/{ref}/pvs": { "post": { "operationId": "createVoucher", "summary": "Raise a payment voucher against a contract", "description": "The machine twin of the agency voucher screen. There is no payee, no bank account and no net figure in the request: the contract supplies the first two and the deduction engine computes the third. The voucher is created against the contract's award number and the full deduction breakdown comes back with the basis sentence for every line.\n\n- net_amount is null until every deductible line has been ticked (BR-17). That is not a redaction: the column is NULL, because a net that has not been agreed does not exist. net_available says which it is.\n\n- A contract that has not been AWARDED carries no award number and is refused with CONTRACT_NOT_FOUND: no voucher exists without a final document number (BR-14).\n\n- Send payee_name, bank_code, account_no, net_amount or withheld_total and the call is refused with VALIDATION_ERROR naming the field. They are not ignored — an integrator who believes they set the net has a bug they need to see.\n\n- The clearance is re-checked for the voucher's fiscal year by POST /pvs/{pv_no}/validate, which is the next call to make.\n\n- Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no voucher is raised meanwhile; the period is fixed at the moment of the request. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.\n\nScope: `pv`.\n\nReason codes: CONTRACT_NOT_FOUND, NOT_FOUND, PV_TCC_STALE, TCC_EXPIRED, DIRECTOR_NONCOMPLIANT, VALIDATION_ERROR, QUEUED_DEGRADED, SCOPE_MISSING, API_DISABLED.", "tags": [ "Vouchers" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "Contract reference, CON-YYYY-XXXXXX.", "schema": { "type": "string", "example": "CON-2026-000318" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pv_type": { "type": "string", "description": "Which kind of payment this is. Defaults to contract.", "enum": [ "contract", "part", "retention", "adjustment" ] }, "gross_amount": { "type": "number", "description": "Gross payable before deductions, greater than zero. Cumulative gross may not exceed the sum plus approved variations.", "example": 42000000 }, "description": { "type": "string", "description": "What is being paid for, at most 500 characters.", "example": "Interim valuation 2" }, "invoice_ref": { "type": "string", "description": "The contractor's invoice reference." }, "period": { "type": "string", "description": "YYYY-MM the payment belongs to. Defaults to the current period." } }, "required": [ "pv_type", "gross_amount" ], "example": { "pv_type": "part", "gross_amount": 42000000, "description": "Interim valuation 2", "invoice_ref": "INV-0442" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "voucher": { "type": "object", "properties": { "pv_no": { "type": "string", "description": "PV-{TYPE}-{YYYY}-{MDA}-{XXXXXX}." }, "pv_type": { "type": "string", "description": "As raised." }, "status": { "type": "string", "description": "DRAFT, VALIDATED, TICKED, FC_APPROVED, WARRANTED, AG_APPROVED, SCHEDULED, RELEASED, PAID, RETURNED or REJECTED." }, "mda": { "type": "string", "description": "The paying agency." }, "award_number": { "type": "string", "description": "The award or authority the voucher is drawn on. No voucher exists without one (BR-14)." }, "payee": { "type": "string", "description": "Taken from the award, never from the request." }, "entity_type": { "type": "string", "description": "The payee's entity type; it decides which heads apply." }, "description": { "type": "string", "description": "As raised.", "nullable": true }, "invoice_ref": { "type": "string", "description": "As raised.", "nullable": true }, "gross_amount": { "type": "number", "description": "As raised." }, "withheld_total": { "type": "number", "description": "Sum of deductible lines." }, "net_amount": { "type": "number", "description": "Null until TICKED.", "nullable": true }, "net_available": { "type": "boolean", "description": "False while net_amount is null — the net has not been agreed, so it does not exist." }, "pending_ticks": { "type": "integer", "description": "Deductible lines still awaiting a tick." }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "line_no": { "type": "integer", "description": "Order on the voucher." }, "head": { "type": "string", "description": "The head withheld.", "enum": [ "PAYE", "WHT", "VAT", "STAMP", "SECURITY", "ADMIN", "DEV_LEVY", "CGT", "ADV_RECOVERY", "RETENTION" ] }, "authority": { "type": "string", "description": "Who the money is for.", "enum": [ "ABIA_BIR", "NRS", "LGA", "PENSION", "NHF", "UNION", "TREASURY" ] }, "rev_code": { "type": "string", "description": "The revenue code it is posted to.", "nullable": true }, "revenue_item": { "type": "string", "description": "That code in words.", "nullable": true }, "rate_value": { "type": "number", "description": "The rate applied.", "nullable": true }, "rate_kind": { "type": "string", "description": "percent, flat, band or none." }, "basis": { "type": "string", "description": "The frozen sentence: which rate, on what base, and why." }, "base_amount": { "type": "number", "description": "The base the rate was applied to." }, "amount": { "type": "number", "description": "The computed figure, rounded half-up to two decimals independently of every other line." }, "applicability": { "type": "string", "description": "settled_at_award = already paid on award, never withheld twice.", "enum": [ "deductible", "settled_at_award", "not_applicable" ] }, "na_reason": { "type": "string", "description": "Why the head does not apply.", "nullable": true }, "status": { "type": "string", "description": "withheld = the treasury deducts it; settled = the payee already paid it.", "enum": [ "pending", "withheld", "settled" ] }, "settled_ref": { "type": "string", "description": "The payment that settled it, when it was settled outside this voucher.", "nullable": true }, "provisional": { "type": "boolean", "description": "True while the rate card awaits confirmation by the Directorate." } }, "required": [ "line_no", "head", "authority", "rate_kind", "basis", "base_amount", "amount", "applicability", "status", "provisional" ] }, "description": "One line per head, in statutory order." }, "fiscal_year": { "type": "integer", "description": "The year the clearance must cover.", "nullable": true }, "period": { "type": "string", "description": "YYYY-MM.", "nullable": true }, "payment_code": { "type": "string", "description": "Minted at treasury approval; the one string that ties voucher, schedule line, covering letter, bank narration and credit note together (FR-7.16).", "nullable": true }, "paid_at": { "type": "string", "description": "When the money left.", "nullable": true }, "return_reason": { "type": "string", "description": "Why it was returned to the maker.", "nullable": true }, "reject_reason": { "type": "string", "description": "Why it was rejected.", "nullable": true }, "created_at": { "type": "string", "description": "When it was raised.", "nullable": true } }, "required": [ "pv_no", "pv_type", "status", "mda", "award_number", "payee", "entity_type", "gross_amount", "withheld_total", "net_available", "pending_ticks", "deductions" ], "description": "The voucher." }, "message": { "type": "string", "description": "What happens next, in a sentence." } }, "required": [ "voucher", "message" ], "description": "The result of this call." } }, "example": { "ok": true, "verification_id": "VRF-2026-9F3C1D7A4B2E", "timestamp": "2026-09-14T09:12:44+01:00", "request": { "id": "a71f3c9d2b40", "ip": "102.89.44.10", "client": "CLI-2026-004417", "mda": "20008001", "env": "sandbox", "echo": {} }, "data": { "voucher": { "pv_no": "PV-PAR-2026-11010001-000318", "pv_type": "part", "status": "DRAFT", "mda": "11010001", "award_number": "AB/DPO/AWRD/2026/9K41XA/TCC-2026-004418", "payee": "Sandbox Compliant Holdings Limited", "entity_type": "llc", "description": "Interim valuation 2", "invoice_ref": "INV-0442", "gross_amount": 42000000, "withheld_total": 4515000, "net_amount": null, "net_available": false, "pending_ticks": 4, "deductions": [ { "line_no": 1, "head": "STAMP", "authority": "ABIA_BIR", "rev_code": null, "revenue_item": null, "rate_value": null, "rate_kind": "none", "basis": "Stamp duty settled on award under payment ABP-2026-77003318; not withheld again (BR-12)", "base_amount": 0, "amount": 0, "applicability": "settled_at_award", "na_reason": null, "status": "settled", "settled_ref": "ABP-2026-77003318", "provisional": false }, { "line_no": 2, "head": "WHT", "authority": "NRS", "rev_code": null, "revenue_item": null, "rate_value": 2.5, "rate_kind": "percent", "basis": "2.5% withholding on construction by a limited company, on gross exclusive of VAT (BR-15)", "base_amount": 42000000, "amount": 1050000, "applicability": "deductible", "na_reason": null, "status": "pending", "settled_ref": null, "provisional": true } ], "fiscal_year": 2026, "period": "2026-09", "payment_code": null, "paid_at": null }, "message": "Raised. Validate it to re-check the clearance, then the deductions are ticked in the console." } } } } } }, "202": { "$ref": "#/components/responses/Queued" }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/contracts/{ref}/variations": { "post": { "operationId": "addVariation", "summary": "Raise a variation on the increment", "description": "Records an increment to the contract. The increment goes through the same award gate as the original sum, so stamp duty is assessed on the increase — a variation is not a way to enlarge a contract behind the duty that was paid on it.\n\n- The increment joins the contract only when a second officer approves the variation in the console (SEC-8), and its own stamp duty is gated first — so a variation is never instantly spendable.\n\n- Cumulative voucher gross is checked against the sum plus APPROVED variations, so a variation must be recorded and approved before the voucher that relies on it.\n\nScope: `transact`.\n\nReason codes: CONTRACT_NOT_FOUND, STAMP_UNPAID, STAMP_SHORTFALL, GATE_PENDING, VALIDATION_ERROR, SCOPE_MISSING, API_DISABLED.", "tags": [ "Contracts" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "Contract reference, CON-YYYY-XXXXXX.", "schema": { "type": "string", "example": "CON-2026-000318" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "The increment in naira, greater than zero.", "example": 18450000 }, "reason": { "type": "string", "description": "Why the variation is being raised, at most 500 characters. Kept with the contract." } }, "required": [ "amount", "reason" ], "example": { "amount": 18450000, "reason": "Additional drainage, approved by EXCO reference EXCO/2026/114" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "contract": { "type": "object", "description": "The contract as it stands after the variation was recorded." }, "variation": { "type": "object", "properties": { "variation_no": { "type": "integer", "description": "Its number on this contract." }, "amount": { "type": "number", "description": "As recorded." }, "reason": { "type": "string", "description": "As given.", "nullable": true }, "status": { "type": "string", "description": "Where the variation sits. This call never returns approved: a second officer does that in the console.", "enum": [ "draft", "gated", "approved", "rejected" ] }, "stamp_status": { "type": "string", "description": "The duty position on the increment." }, "stamp_bill_ref": { "type": "string", "description": "The bill for that duty.", "nullable": true } }, "required": [ "variation_no", "amount", "status", "stamp_status" ], "description": "The variation.", "nullable": true }, "gates_clear": { "type": "boolean", "description": "Whether the gate run on the increment came back eligible." }, "blocking": { "type": "array", "items": { "type": "object" }, "description": "What stands in the way of the increment." }, "message": { "type": "string", "description": "What happens next, in a sentence." } }, "required": [ "contract", "gates_clear", "blocking", "message" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/documents/verify": { "post": { "operationId": "lookupDocument", "summary": "Look a document up by its long number", "description": "The long document number contains forward slashes and a route parameter never spans one, so the full number is carried in the body instead. The answer is the same record GET /documents/{no} returns.\n\n- Nothing is minted, so no Idempotency-Key is required.\n\nScope: `documents`.\n\nReason codes: DOCUMENT_NOT_FOUND, DOCUMENT_VOID, VALIDATION_ERROR, SCOPE_MISSING.", "tags": [ "Documents" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "The long or the short number, exactly as printed. document_number is accepted as a synonym.", "example": "AB/LND/COFO/2026/4F2K7C/TCC-2026-004418" } }, "required": [ "number" ], "example": { "number": "AB/LND/COFO/2026/4F2K7C/TCC-2026-004418" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "document": { "type": "object", "description": "As GET /documents/{no}." }, "transaction_ref": { "type": "string", "description": "Issuing agency only.", "nullable": true }, "evidence_url": { "type": "string", "description": "Issuing agency only: the evidence bundle for this number.", "nullable": true } }, "required": [ "document" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/documents/{no}": { "get": { "operationId": "getDocument", "summary": "Read a final document from the register", "description": "The owning agency sees the whole record. Any other key sees the limited public set — issuer, process, reduced party name, clearance reference and status — because a document number is a verification instrument, not a licence to read another agency's case file.\n\n- {no} is the SHORT number. The long form contains \"/\" and a route parameter never spans one, so post the long number to /documents/verify instead.\n\n- A VOID document still answers, with its whole record in data — but as a refusal carrying DOCUMENT_VOID, because \"this number is void\" is not a favourable answer.\n\nScope: `documents`.\n\nReason codes: DOCUMENT_NOT_FOUND, DOCUMENT_VOID, VALIDATION_ERROR, SCOPE_MISSING.", "tags": [ "Documents" ], "parameters": [ { "name": "no", "in": "path", "required": true, "description": "The short document number.", "schema": { "type": "string", "example": "AB-LND26-4F2K7C" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "document": { "type": "object", "properties": { "document_number": { "type": "string", "description": "Long form." }, "short_number": { "type": "string", "description": "Short form." }, "status": { "type": "string", "description": "A void document still answers — it answers \"void\".", "enum": [ "valid", "void" ] }, "mda": { "type": "string", "description": "Issuing agency, by revenue head." }, "process": { "type": "string", "description": "Process code." }, "process_name": { "type": "string", "description": "Process name.", "nullable": true }, "document_name": { "type": "string", "description": "What was issued, e.g. Certificate of Occupancy." }, "party_display": { "type": "string", "description": "Issued to. An individual is reduced to a masked name on every channel." }, "entity_type": { "type": "string", "description": "Entity type of the holder." }, "tcc_ref": { "type": "string", "description": "The clearance the number embeds." }, "tcc_valid_until": { "type": "string", "description": "Expiry of that clearance.", "nullable": true }, "issued_at": { "type": "string", "description": "Issue timestamp." }, "verification_id": { "type": "string", "description": "The issuance ledger id." }, "verify_url": { "type": "string", "description": "The public verification page." }, "sandbox": { "type": "boolean", "description": "True for a rehearsal document. It is never a state document." }, "void_reason": { "type": "string", "description": "Why it was voided.", "nullable": true }, "void_at": { "type": "string", "description": "When it was voided.", "nullable": true }, "party_name": { "type": "string", "description": "Issuing agency only: the unmasked name.", "nullable": true }, "abssin": { "type": "string", "description": "Issuing agency only.", "nullable": true }, "issued_by": { "type": "string", "description": "Issuing agency only: who minted it.", "nullable": true }, "issued_to_system": { "type": "string", "description": "Issuing agency only: the channel it was minted through.", "nullable": true } }, "required": [ "document_number", "short_number", "status", "mda", "process", "document_name", "party_display", "entity_type", "tcc_ref", "issued_at", "verification_id", "verify_url", "sandbox" ], "description": "The record." }, "transaction_ref": { "type": "string", "description": "Issuing agency only.", "nullable": true }, "evidence_url": { "type": "string", "description": "Issuing agency only.", "nullable": true } }, "required": [ "document" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/documents/{no}/evidence": { "get": { "operationId": "getDocumentEvidence", "summary": "The evidence bundle behind a document", "description": "Every gate as it stood at issuance — status, the frozen basis, the rule version, the assessments raised and the payments matched, and the clearance certificate cited (FR-14.4). This is what an auditor reads a year later, and it is available to the owning agency only.\n\n- The bundle is versioned and hashed. Store the sha256 with your copy: it is how a printed bundle is proved identical to the one the platform holds.\n\nScope: `documents`.\n\nReason codes: DOCUMENT_NOT_FOUND, NOT_FOUND, SCOPE_MISSING.", "tags": [ "Documents" ], "parameters": [ { "name": "no", "in": "path", "required": true, "description": "The short document number.", "schema": { "type": "string", "example": "AB-LND26-4F2K7C" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "document_number": { "type": "string", "description": "The document, in long form." }, "version": { "type": "integer", "description": "Bundle version." }, "sha256": { "type": "string", "description": "Hash of the bundle as returned." }, "evidence": { "type": "object", "description": "The bundle itself: the gates with their basis and rule version, the assessments with frozen inputs, the payments matched, and the clearance cited." } }, "required": [ "document_number", "version", "sha256", "evidence" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/dw/extracts": { "get": { "operationId": "listDwExtracts", "summary": "List the recent data-warehouse extracts", "description": "One extract per day: a gzipped JSON-lines file per dataset and a manifest naming each file with its row count and sha256. Each day is a delta — the rows created or changed inside that day — so a rebuilt day reproduces itself and a warehouse can replay a gap. No file carries a national identity number, bank verification number, TIN, phone or email.\n\n- Live keys only. A sandbox key is refused with SCOPE_MISSING even when it holds dw: the warehouse is fed from live data.\n\n- Newest first. ?limit= takes 1 to 60 days; the default is 30, which is also the retention.\n\n- available is true when the day is ready AND its files are still on disk; only then is manifest_url set.\n\n- complete=false marks a day extracted before it ended. It will be rebuilt, so collect it again.\n\nScope: `dw`.\n\nReason codes: SCOPE_MISSING.", "tags": [ "Warehouse" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Days to list, 1 to 60. Default 30.", "schema": { "type": "integer", "example": 30 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "env": { "type": "string", "description": "Always live.", "enum": [ "live" ] }, "retention_days": { "type": "integer", "description": "How long an extract is kept before it is deleted." }, "datasets": { "type": "array", "items": { "type": "string" }, "description": "Every dataset an extract carries, in file order." }, "extracts": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM-DD." }, "status": { "type": "string", "description": "Where the day's build stands.", "enum": [ "building", "ready", "failed", "expired" ] }, "available": { "type": "boolean", "description": "Whether it can be collected now." }, "complete": { "type": "boolean", "description": "False when the day had not ended when it was extracted.", "nullable": true }, "schema_version": { "type": "integer", "description": "Bumped when a dataset's shape changes in a way a consumer must notice.", "nullable": true }, "file_count": { "type": "integer", "description": "Files in the extract." }, "total_rows": { "type": "integer", "description": "Rows across every file." }, "total_bytes": { "type": "integer", "description": "Compressed bytes across every file." }, "built_at": { "type": "string", "description": "When the build finished.", "nullable": true }, "expires_at": { "type": "string", "description": "When retention deletes it.", "nullable": true }, "manifest_url": { "type": "string", "description": "GET /dw/extracts/{date}, when available.", "nullable": true } }, "required": [ "date", "status", "available", "file_count", "total_rows", "total_bytes" ] }, "description": "One entry per day." } }, "required": [ "env", "retention_days", "datasets", "extracts" ], "description": "The result of this call." } }, "example": { "ok": true, "verification_id": "VRF-2026-9F3C1D7A4B2E", "timestamp": "2026-09-14T09:12:44+01:00", "request": { "id": "a71f3c9d2b40", "ip": "102.89.44.10", "client": "CLI-2026-004417", "mda": "20008001", "env": "sandbox", "echo": {} }, "data": { "env": "live", "retention_days": 30, "datasets": [ "parties", "tcc", "transactions" ], "extracts": [ { "date": "2026-09-13", "status": "ready", "available": true, "complete": true, "schema_version": 1, "file_count": 12, "total_rows": 18422, "total_bytes": 1204116, "built_at": "2026-09-14 01:15:09", "expires_at": "2026-10-14 01:15:09", "manifest_url": "https://services.abiastate.gov.ng/api/v1/dw/extracts/2026-09-13" } ] } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/dw/extracts/{date}": { "get": { "operationId": "getDwManifest", "summary": "Read one day's extract manifest", "description": "The manifest exactly as the extract wrote it — window, completeness, privacy statement and every file — with a download URL added to each file. The manifest is written last, so its presence is what says the day's set is whole.\n\n- Verify each file against its sha256 after download. The platform checks it before sending as well, and never sends a file that does not match.\n\n- Money and other decimal columns are JSON strings inside the files, so no precision is lost in transit.\n\n- A day that was never built, has expired, or is being rebuilt right now is NOT_FOUND. Try again later for a rebuild.\n\nScope: `dw`.\n\nReason codes: NOT_FOUND, VALIDATION_ERROR, SCOPE_MISSING.", "tags": [ "Warehouse" ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "The extract day, YYYY-MM-DD.", "schema": { "type": "string", "example": "2026-09-13" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "date": { "type": "string", "description": "The day asked for." }, "manifest": { "type": "object", "properties": { "schema_version": { "type": "integer", "description": "Dataset shape version." }, "env": { "type": "string", "description": "live." }, "extract_date": { "type": "string", "description": "YYYY-MM-DD." }, "window": { "type": "object", "description": "from, to and the basis of the delta." }, "complete": { "type": "boolean", "description": "False when extracted before the day ended." }, "generated_at": { "type": "string", "description": "When the extract was written." }, "privacy": { "type": "string", "description": "What the files never carry." }, "numbers": { "type": "string", "description": "How decimals are encoded." }, "file_count": { "type": "integer", "description": "Files listed below." }, "total_rows": { "type": "integer", "description": "Rows across every file." }, "total_bytes": { "type": "integer", "description": "Compressed bytes across every file." }, "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "{dataset}.jsonl.gz." }, "rows": { "type": "integer", "description": "JSON lines in the file." }, "bytes": { "type": "integer", "description": "Compressed size." }, "sha256": { "type": "string", "description": "Hex sha256 of the compressed file." }, "url": { "type": "string", "description": "GET /dw/extracts/{date}/{name}." } }, "required": [ "name", "rows", "bytes", "sha256", "url" ] }, "description": "One entry per dataset file." } }, "required": [ "schema_version", "env", "extract_date", "window", "complete", "generated_at", "privacy", "numbers", "file_count", "total_rows", "total_bytes", "files" ], "description": "The manifest." } }, "required": [ "date", "manifest" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/dw/extracts/{date}/{name}": { "get": { "operationId": "getDwFile", "summary": "Download one extract file", "description": "The file itself, as application/gzip — not a JSON envelope. The platform reads the file, checks its sha256 against the manifest and sends exactly the bytes it checked. Refusals are still the usual JSON envelope.\n\n- The name must be one the manifest lists for that date; anything else is NOT_FOUND.\n\n- X-Content-SHA256 carries the verified hash and X-Extract-Rows the line count. Cache-Control is private, no-store: do not put a caching proxy in front of this call.\n\n- A file that fails its integrity check is not sent: the answer is a retryable INTERNAL_ERROR and the day is rebuilt by the Board.\n\n- Files larger than 48 MB are not served over the API and are refused with VALIDATION_ERROR; collect those by SFTP.\n\nScope: `dw`.\n\nReason codes: NOT_FOUND, VALIDATION_ERROR, INTERNAL_ERROR, SCOPE_MISSING.", "tags": [ "Warehouse" ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "The extract day, YYYY-MM-DD.", "schema": { "type": "string", "example": "2026-09-13" } }, { "name": "name", "in": "path", "required": true, "description": "A file name from that day's manifest.", "schema": { "type": "string", "example": "parties.jsonl.gz" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The file, verified against the manifest before it was sent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Extract-Rows": { "$ref": "#/components/headers/ExtractRows" } }, "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/parties": { "post": { "operationId": "registerParty", "summary": "Register a party the state register does not hold", "description": "Mints a state identification number on the spot so a transaction is never blocked by the absence of an identity (FR-1.6). A company or a business name is registered outright. An individual is registered in the SANDBOX only: in live an ABSSIN is issued only against a photograph captured live, which a server-to-server call cannot perform, so the call is refused with PARTY_UNREGISTERED and a link to the public registration journey.\n\n- The answer is the same body /parties/verify returns — party, compliant, reason_codes, remediation_url — so one parser handles both.\n\n- An RC number already on the register is a REFUSAL (VALIDATION_ERROR, field rc_number) that carries the existing party in data.party. Continue with that party; do not retry.\n\n- Degraded mode: while the taxpayer register or the ABSSIN registration service are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no identity is claimed or minted meanwhile. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.\n\n- Only a company or business name is ever queued. An individual's registration rests on a liveness capture valid only in the moment it is taken, so it is never held: while upstream is down it is refused, and should be retried later.\n\n- The queue never stores an identity number. A director named only by NIN is queued by the ABSSIN the platform already holds for that person; if it holds none, the call answers a retryable INTERNAL_ERROR — retry later, or name the director by abssin.\n\nScope: `transact`.\n\nReason codes: PARTY_UNREGISTERED, VALIDATION_ERROR, QUEUED_DEGRADED, SCOPE_MISSING.", "tags": [ "Parties" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "Entity type to register.", "enum": [ "individual", "business_name", "llc" ] }, "name": { "type": "string", "description": "Corporate: name as registered with the CAC. Required for business_name and llc.", "example": "Umuahia Civil Works Limited" }, "rc_number": { "type": "string", "description": "Corporate: CAC registration number. Required for business_name and llc.", "example": "RC1284410" }, "phone": { "type": "string", "description": "Corporate: contact phone. Required.", "example": "08030000002" }, "email": { "type": "string", "description": "Corporate: contact email. Required." }, "lga_id": { "type": "integer", "description": "Corporate: local government area of the registered address. Required." }, "address": { "type": "string", "description": "Corporate: registered address. Required." }, "tin": { "type": "string", "description": "TIN where the entity holds one." }, "directors": { "type": "array", "items": { "type": "object" }, "description": "Corporate: the directors, or the proprietor of a business name, who are the subjects of the clearance check (BR-10/BR-11)." }, "first_name": { "type": "string", "description": "Individual (sandbox only): given name. Required." }, "middle_name": { "type": "string", "description": "Individual (sandbox only): middle name." }, "surname": { "type": "string", "description": "Individual (sandbox only): surname. Required." } }, "required": [ "kind" ], "example": { "kind": "llc", "name": "Umuahia Civil Works Limited", "rc_number": "RC1284410", "phone": "08030000002", "email": "accounts@ucw.example.ng", "lga_id": 12, "address": "4 Bende Road, Umuahia" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "party": { "type": "object", "description": "The registered party, exactly as /parties/verify shapes it — party_ref, kind, display_name, abssin, rc_number, tin, contact and, where read, tax_clearance." }, "compliant": { "type": "boolean", "description": "The clearance position of the party just registered." }, "reason_codes": { "type": "array", "items": { "type": "string" }, "description": "Codes standing against it — a fresh registration usually has none but TCC_MISSING." }, "remediation_url": { "type": "string", "description": "Where the party regularises.", "nullable": true } }, "required": [ "party", "compliant", "reason_codes" ], "description": "The result of this call." } } } } } }, "202": { "$ref": "#/components/responses/Queued" }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/parties/validate": { "post": { "operationId": "validateParty", "summary": "Ask whether an applicant may proceed, on a fee-less process", "description": "The expression-of-interest check (FR-10.3): a real transaction on a fee-less process, judged by the same gate engine an officer would use, so an applicant's journey cannot show a different answer from the counter's. It answers one question — may this ABSSIN proceed — and names every gate that says otherwise.\n\n- This runs the gates, so it creates a transaction and returns its reference. It is not a read; do not call it in a loop.\n\n- Two verification ids are in play: the envelope's own, and gate_verification_id for the gate run. A later dispute cites the second.\n\n- A blocked applicant comes back ok=false with the first blocking code — and data is still present, carrying the transaction reference and the full blocking list.\n\nScope: `verify`.\n\nReason codes: PARTY_NOT_FOUND, PROCESS_NOT_CONFIGURED, TCC_MISSING, TCC_EXPIRED, TCC_STALE_FOR_YEAR, DIRECTOR_NONCOMPLIANT, PROPRIETOR_NONCOMPLIANT, GATE_PENDING, VALIDATION_ERROR, SCOPE_MISSING.", "tags": [ "Parties" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "abssin": { "type": "string", "description": "The applicant's state identification number (state_id is accepted as a synonym).", "example": "SBX0000101" }, "process": { "type": "string", "description": "The process, as {AGENCY_CODE}/{PROCESS_CODE}. Defaults to HSG/EOI.", "example": "HSG/EOI" } }, "required": [ "abssin" ], "example": { "abssin": "SBX0000101", "process": "HSG/EOI" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "may_proceed": { "type": "boolean", "description": "True when every applicable gate is clear." }, "process": { "type": "string", "description": "The process the answer was judged against." }, "transaction_ref": { "type": "string", "description": "The transaction the gate run created.", "nullable": true }, "gate_verification_id": { "type": "string", "description": "The verification id the gate run itself recorded.", "nullable": true }, "blocking": { "type": "array", "items": { "type": "object", "properties": { "gate": { "type": "string", "description": "TCC, CGT, STAMP, FEE or BR." }, "reason_code": { "type": "string", "description": "The published code for this gate.", "nullable": true }, "subject": { "type": "string", "description": "Who the gate is about, when it is not the entity.", "nullable": true }, "amount_due": { "type": "number", "description": "What is payable to clear it.", "nullable": true }, "message": { "type": "string", "description": "The catalogue message with the subject filled in.", "nullable": true } }, "required": [ "gate" ] }, "description": "One entry per gate that is not clear. Empty when may_proceed is true." }, "message": { "type": "string", "description": "A sentence for the applicant's screen.", "nullable": true } }, "required": [ "may_proceed", "process", "blocking" ], "description": "The result of this call." } }, "example": { "ok": true, "verification_id": "VRF-2026-9F3C1D7A4B2E", "timestamp": "2026-09-14T09:12:44+01:00", "request": { "id": "a71f3c9d2b40", "ip": "102.89.44.10", "client": "CLI-2026-004417", "mda": "20008001", "env": "sandbox", "echo": {} }, "data": { "may_proceed": true, "process": "HSG/EOI", "transaction_ref": "BTX-2026-004870", "gate_verification_id": "VRF-2026-7C1A9E4D2B08", "blocking": [], "message": null } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/parties/verify": { "post": { "operationId": "verifyParty", "summary": "Resolve a taxpayer and read their compliance position", "description": "Resolves ONE identifier to a party on the state register and returns the clearance position of the entity and, for a company, of every active director (BR-10); for a business name, of the proprietor (BR-11). This is a POST and not a GET because the identifier may be a national identity number, and those must never appear in a URL, a proxy log or an access log.\n\n- Send ONE identifier. If more than one is present the first of abssin, nin, rc, tin, party_ref is the one used — so do not send two and expect them to be cross-checked.\n\n- A party that resolves but is NOT compliant is not an error: ok=true, data.compliant=false, and data.reason_codes names every published code that applies, with data.remediation_url pointing at the page that fixes the first of them. The refusal with a reason code happens where a decision is actually being asked for — a transaction, an award or a voucher.\n\n- The NIN is never returned, not even masked; data.party.has_nin only says whether the register holds one. An individual's phone and email are masked unless the calling agency created or last touched the record (a corporate contact is public and is never masked).\n\n- The clearance position is always read for the CURRENT year. There is no year parameter on this endpoint; a voucher or a transaction is where a specific fiscal year is judged.\n\nScope: `verify`.\n\nReason codes: PARTY_NOT_FOUND, VALIDATION_ERROR, SCOPE_MISSING.", "tags": [ "Parties" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "abssin": { "type": "string", "description": "The state identification number (state_id is accepted as a synonym).", "example": "SBX0000102" }, "nin": { "type": "string", "description": "National identity number. Never logged, never echoed." }, "rc": { "type": "string", "description": "CAC registration number of a company or business name. The field is `rc`, not `rc_no`.", "example": "RC9900102" }, "tin": { "type": "string", "description": "Taxpayer identification number." }, "party_ref": { "type": "string", "description": "A party reference the platform issued earlier (BPR-YYYY-XXXXXX)." }, "kind": { "type": "string", "description": "The explicit form: name the kind and put the identifier in `value`.", "enum": [ "abssin", "nin", "rc", "tin", "party_ref" ] }, "value": { "type": "string", "description": "The identifier, when `kind` is given." } }, "example": { "abssin": "SBX0000102" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "party": { "type": "object", "properties": { "party_ref": { "type": "string", "description": "BPR-YYYY-XXXXXX." }, "kind": { "type": "string", "description": "Entity type; it decides which rules apply.", "enum": [ "individual", "business_name", "llc", "other" ] }, "display_name": { "type": "string", "description": "Registered name." }, "abssin": { "type": "string", "description": "State identification number, where the party holds one.", "nullable": true }, "rc_number": { "type": "string", "description": "CAC number where held.", "nullable": true }, "tin": { "type": "string", "description": "TIN where held.", "nullable": true }, "lga_id": { "type": "integer", "description": "Local government area of the registered address.", "nullable": true }, "status": { "type": "string", "description": "Register status of the party." }, "has_nin": { "type": "boolean", "description": "Whether the register holds a NIN. The number itself never leaves." }, "cac_verified_at": { "type": "string", "description": "When the RC number was last verified upstream.", "nullable": true }, "contact": { "type": "object", "properties": { "phone": { "type": "string", "description": "Contact phone, masked when redacted is true.", "nullable": true }, "email": { "type": "string", "description": "Contact email, masked when redacted is true.", "nullable": true }, "redacted": { "type": "boolean", "description": "True when the values above are masked." } }, "required": [ "redacted" ], "description": "Phone and email; masked for an individual outside the owning agency." }, "tax_clearance": { "type": "object", "properties": { "held": { "type": "boolean", "description": "Whether a certificate is held at all." }, "reference": { "type": "string", "description": "Certificate reference.", "nullable": true }, "year": { "type": "integer", "description": "Year of assessment the certificate covers.", "nullable": true }, "valid_until": { "type": "string", "description": "Expiry date, YYYY-MM-DD.", "nullable": true } }, "required": [ "held" ], "description": "The entity clearance position. Absent when the registry could not be read." }, "outstanding": { "type": "object", "properties": { "count": { "type": "integer", "description": "Unpaid bills." }, "total": { "type": "number", "description": "Total outstanding." }, "available": { "type": "boolean", "description": "False when the figure could not be computed; treat the total as unknown, not as zero." } }, "required": [ "count", "total", "available" ], "description": "What the party owes across the platform." }, "directors": { "type": "array", "items": { "type": "object", "properties": { "party_ref": { "type": "string", "description": "The director as a party in their own right." }, "name": { "type": "string", "description": "Director name." }, "role": { "type": "string", "description": "director, proprietor or signatory." }, "tcc_held": { "type": "boolean", "description": "Whether this subject holds a certificate." }, "tcc_ref": { "type": "string", "description": "Their certificate reference.", "nullable": true }, "valid_until": { "type": "string", "description": "Expiry of their certificate.", "nullable": true } }, "required": [ "party_ref", "name", "role", "tcc_held" ] }, "description": "Directors, or the proprietor of a business name." } }, "required": [ "party_ref", "kind", "display_name", "status", "has_nin", "contact" ], "description": "The resolved party." }, "compliant": { "type": "boolean", "description": "True only when reason_codes is empty — the entity AND every checked subject is clear." }, "reason_codes": { "type": "array", "items": { "type": "string" }, "description": "Every published code that stands against this party. Empty when compliant." }, "remediation_url": { "type": "string", "description": "A link the taxpayer can open and act on. Null when compliant.", "nullable": true } }, "required": [ "party", "compliant", "reason_codes" ], "description": "The result of this call." } }, "example": { "ok": true, "verification_id": "VRF-2026-9F3C1D7A4B2E", "timestamp": "2026-09-14T09:12:44+01:00", "request": { "id": "a71f3c9d2b40", "ip": "102.89.44.10", "client": "CLI-2026-004417", "mda": "20008001", "env": "sandbox", "echo": {} }, "data": { "party": { "party_ref": "BPR-2026-000914", "kind": "llc", "display_name": "Sandbox Blocked Ventures Limited", "abssin": "SBX0000102", "rc_number": "RC9900102", "tin": null, "lga_id": null, "status": "active", "has_nin": false, "cac_verified_at": null, "contact": { "phone": null, "email": "sandbox@abiaone.test", "redacted": false }, "tax_clearance": { "held": true, "reference": "TCC/2026/004418", "year": 2026, "valid_until": "2026-12-31" }, "outstanding": { "count": 0, "total": 0, "available": true }, "directors": [ { "party_ref": "BPR-2026-000915", "name": "Ngozi Sandbox Director", "role": "director", "tcc_held": true, "tcc_ref": "TCC/2026/004419", "valid_until": "2026-12-31" }, { "party_ref": "BPR-2026-000916", "name": "Uche Sandbox Nocert", "role": "director", "tcc_held": false, "tcc_ref": null, "valid_until": null } ] }, "compliant": false, "reason_codes": [ "DIRECTOR_NONCOMPLIANT" ], "remediation_url": "https://services.abiastate.gov.ng/me/tcc" } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/parties/{ref}": { "get": { "operationId": "getParty", "summary": "Read a party you already hold a reference for", "description": "The same record /parties/verify returns, addressed by the reference the platform issued. Safe in a URL because a party reference is not an identity number — that is precisely why the platform hands you one.\n\n- Store the party_ref against your own applicant record and use this endpoint afterwards; there is then no reason for a national identity number to be in your system at all.\n\n- A reference belonging to the other environment reads as PARTY_NOT_FOUND: sandbox and live must not be able to prove each other's rows exist.\n\nScope: `verify`.\n\nReason codes: PARTY_NOT_FOUND, VALIDATION_ERROR, SCOPE_MISSING.", "tags": [ "Parties" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "Party reference, BPR-YYYY-XXXXXX.", "schema": { "type": "string", "example": "BPR-2026-000914" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "party": { "type": "object", "description": "As /parties/verify." }, "compliant": { "type": "boolean", "description": "Clearance position for the current year." }, "reason_codes": { "type": "array", "items": { "type": "string" }, "description": "Codes standing against the party." }, "remediation_url": { "type": "string", "description": "Where they fix it.", "nullable": true } }, "required": [ "party", "compliant", "reason_codes" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/paye/events": { "post": { "operationId": "payeEvents", "summary": "Notify a payroll run", "description": "Tell the Board what a payroll deducted, line by line. One call per run per employer per month. The Board posts one aggregate row to the revenue ledger and reconciles what you notified against what actually arrived.\n\n- event_id is YOURS and it is the idempotency key that matters: send the same run twice and the second call replays the first answer, including its verification id, rather than posting the money again. Use the payroll system's own run identifier, not a timestamp.\n\n- The totals must equal the sum of the lines. A run whose figures disagree with itself is refused rather than half-accepted — the reconciliation that follows would otherwise be chasing a difference that was never real.\n\n- Send the national identity number only if you hold it lawfully. It is hashed on arrival and the clear value is never stored, so it cannot be read back — the ABSSIN is what ties a line to a person on our side.\n\nScope: `pay`.\n\nReason codes: VALIDATION_ERROR, SCOPE_MISSING, IDEMPOTENCY_KEY_REUSED, INTERNAL_ERROR, API_DISABLED.", "tags": [ "PAYE" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Your run identifier. Unique per employer per period; a repeat replays." }, "employer_kind": { "type": "string", "description": "mda, lga, parastatal or private." }, "employer_name": { "type": "string", "description": "As it should read on the reconciliation." }, "mda": { "type": "string", "description": "The revenue head, when the employer is an agency." }, "pay_period": { "type": "string", "description": "YYYY-MM." }, "payment_date": { "type": "string", "description": "When the payroll was paid." }, "heading_code": { "type": "string", "description": "STATE_PAYE or LGA_PAYE. Defaults to STATE_PAYE." }, "totals": { "type": "object", "description": "gross, taxable, paye and staff_count for the whole run." }, "lines": { "type": "array", "items": { "type": "object" }, "description": "One per member of staff: staff_id, abssin, name, residence_lga, gross, taxable, paye." } }, "required": [ "event_id", "employer_kind", "pay_period", "totals", "lines" ], "example": { "event_id": "UPMAS-2026-09-MOE-0041", "employer_kind": "mda", "employer_name": "Ministry of Basic Education", "mda": "17001001", "pay_period": "2026-09", "heading_code": "STATE_PAYE", "totals": { "gross": 48250000, "taxable": 41300000, "paye": 5162500, "staff_count": 412 }, "lines": [ { "staff_id": "MOE/4411", "abssin": "1189370162", "name": "A. Okoro", "residence_lga": "Umuahia North", "gross": 180000, "taxable": 154000, "paye": 19250 } ] } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "event": { "type": "object", "description": "The stored run: its status, its line count and the verification id a duplicate will replay." }, "replayed": { "type": "boolean", "description": "True when this run was already known and nothing was written." } }, "required": [ "event", "replayed" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/paye/upload": { "post": { "operationId": "payeUpload", "summary": "Notify a payroll run as a file", "description": "The same notification as POST /paye/events, for a payroll system that can produce a file more easily than a JSON body. Kept deliberately, because the alternative to a supported upload is a spreadsheet sent by email.\n\n- The file travels INSIDE the JSON body, base64 in csv_base64 or plain text in csv — not as a multipart form. Idempotency and request signing both hash the raw body, and neither can see a multipart part, so a multipart upload would have no replay protection at all.\n\n- Columns: staff_id, abssin, name, residence_lga, gross, taxable, paye. The header row names them; order does not matter.\n\n- Without an event_id the file's own hash becomes one, so re-sending an identical file replays instead of posting twice.\n\nScope: `pay`.\n\nReason codes: VALIDATION_ERROR, SCOPE_MISSING, TOO_LARGE, IDEMPOTENCY_KEY_REUSED, INTERNAL_ERROR, API_DISABLED.", "tags": [ "PAYE" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Yours if you have one; otherwise derived from the file hash." }, "employer_kind": { "type": "string", "description": "mda, lga, parastatal or private." }, "pay_period": { "type": "string", "description": "YYYY-MM." }, "csv_base64": { "type": "string", "description": "The file, base64 encoded. Use this or csv." }, "csv": { "type": "string", "description": "The file as plain text, for a small run." } }, "required": [ "employer_kind", "pay_period" ], "example": { "event_id": "MOE-2026-09", "employer_kind": "mda", "pay_period": "2026-09", "csv": "staff_id,abssin,name,residence_lga,gross,taxable,paye\nMOE/4411,1189370162,A. Okoro,Umuahia North,180000,154000,19250\n" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "event": { "type": "object", "description": "The stored run, as POST /paye/events returns it." }, "replayed": { "type": "boolean", "description": "True when this file was already known." } }, "required": [ "event", "replayed" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/payments/advice": { "post": { "operationId": "paymentAdvice", "summary": "Advise a collection against a verification", "description": "An agency system telling the platform that money was collected for an answer the platform gave. The verification id is mandatory and must exist (SEC-5, FR-11.5): a payment that cites no verification is refused, because a collection with no verification behind it is exactly the leak this platform exists to close.\n\n- The verification must be one this client was answered with, in this environment. Someone else's verification is as good as none.\n\n- The transaction is taken from the verification. Send transaction_ref only when the verification does not name one.\n\n- The reference is then checked against the central ledger: unknown, unsettled, wrong amount, wrong payer or already spent are all refusals, each with its own code.\n\n- Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — the verification citation is checked at once, but the reference is neither matched nor refused until the ledger can be read. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.\n\nScope: `pay`.\n\nReason codes: PAYMENT_NO_VERIFICATION, PAYMENT_REF_UNKNOWN, PAYMENT_NOT_SETTLED, PAYMENT_AMOUNT_MISMATCH, PAYMENT_PARTY_MISMATCH, PAYMENT_HEAD_MISMATCH, PAYMENT_DUPLICATE, NOT_FOUND, VALIDATION_ERROR, QUEUED_DEGRADED.", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "verification_id": { "type": "string", "description": "The id from the answer this collection followed.", "example": "VRF-2026-9F3C1D7A4B2E" }, "reference": { "type": "string", "description": "The reference in the collection ledger, at most 80 characters.", "example": "ABP-2026-77120043" }, "head": { "type": "string", "description": "The head the money was collected for. Defaults to FEE.", "enum": [ "CGT", "STAMP", "FEE", "TCC" ] }, "amount": { "type": "number", "description": "Amount collected. A disagreement with the ledger is refused, not reconciled.", "example": 2500000 }, "transaction_ref": { "type": "string", "description": "The case the money belongs to, when the verification does not name one." } }, "required": [ "verification_id", "reference" ], "example": { "verification_id": "VRF-2026-9F3C1D7A4B2E", "reference": "ABP-2026-77120043", "amount": 2500000, "head": "CGT" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "matched": { "type": "boolean", "description": "Whether the evidence was accepted." }, "head": { "type": "string", "description": "The head it was applied to." }, "reference": { "type": "string", "description": "As cited." }, "message": { "type": "string", "description": "What the evidence service made of it.", "nullable": true }, "transaction": { "type": "object", "description": "The transaction view after re-running the gates." } }, "required": [ "matched", "head", "reference", "transaction" ], "description": "The result of this call." } } } } } }, "202": { "$ref": "#/components/responses/Queued" }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/ping": { "get": { "operationId": "ping", "summary": "Prove a key and read its limits", "description": "The first call an integrator makes. It proves the credential, shows which environment the key belongs to, which scopes it carries and what it is allowed per minute — and it returns a verification id, so the envelope is seen before anything real happens.\n\n- No scope required: any active key may call it.\n\nReason codes: AUTH_INVALID, CLIENT_SUSPENDED, IP_NOT_ALLOWED, TLS_REQUIRED, RATE_LIMITED, API_DISABLED.", "tags": [ "Connectivity" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "client": { "type": "string", "description": "Client reference (CLI-YYYY-XXXXXX).", "example": "CLI-2026-004417" }, "mda": { "type": "string", "description": "The revenue head the key is scoped to. Every call is filtered by it.", "example": "20008001" }, "env": { "type": "string", "description": "Decided by the key, never by the caller.", "enum": [ "live", "sandbox" ], "example": "sandbox" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes this client holds.", "example": [ "verify", "transact", "documents" ] }, "signed": { "type": "boolean", "description": "Whether this request carried a verified signature." }, "rate_per_minute": { "type": "integer", "description": "Requests per minute allowed for this client.", "example": 120 }, "server_time": { "type": "string", "description": "Server clock, ISO-8601. Use it to correct skew before signing.", "example": "2026-09-14T09:12:44+01:00" }, "version": { "type": "string", "description": "API version serving this path.", "example": "v1" } }, "required": [ "client", "mda", "env", "scopes", "signed", "rate_per_minute", "server_time", "version" ], "description": "The result of this call." } }, "example": { "ok": true, "verification_id": "VRF-2026-9F3C1D7A4B2E", "timestamp": "2026-09-14T09:12:44+01:00", "request": { "id": "a71f3c9d2b40", "ip": "102.89.44.10", "client": "CLI-2026-004417", "mda": "20008001", "env": "sandbox", "echo": {} }, "data": { "client": "CLI-2026-004417", "mda": "20008001", "env": "sandbox", "scopes": [ "verify", "transact", "documents" ], "signed": false, "rate_per_minute": 120, "server_time": "2026-09-14T09:12:44+01:00", "version": "v1" } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/public/documents/verify": { "post": { "operationId": "verifyDocumentPublicByNumber", "summary": "Verify a long document number without a key", "description": "The unauthenticated twin of /documents/verify, for a number printed in its long form. Same limited answer as the public GET: issuer, process, reduced name, clearance reference and status. Throttled per address.\n\nReason codes: DOCUMENT_NOT_FOUND, DOCUMENT_VOID, RATE_LIMITED, API_DISABLED.", "tags": [ "Documents" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "The number as printed, long or short. document_number is accepted as a synonym.", "example": "AB/LND/COFO/2026/4F2K7C/TCC-2026-004418" } }, "required": [ "number" ], "example": { "number": "AB-LND26-4F2K7C" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "document": { "type": "object", "description": "The public fields, as GET /public/documents/{no}." } }, "required": [ "document" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/public/documents/{no}": { "get": { "operationId": "verifyDocumentPublic", "summary": "Verify a document number without a key", "description": "The machine twin of the public verification page. No credential, no personal data: the issuer, what was issued, a reduced name, the clearance reference and whether the document is genuine and still valid. Throttled per address, and every lookup is written to the verification ledger with the caller's address.\n\n- Use this to verify a document presented to you; use GET /documents/{no} to read one you issued. For a number printed in its long form, post it to /public/documents/verify.\n\n- A number that is not on the register answers ok=false with DOCUMENT_NOT_FOUND and no data. A number that is VOID answers ok=false with DOCUMENT_VOID and the record in data — being told it is void is the point.\n\n- request.client, request.mda and request.env are null on this route: there is no key, so there is nothing to name.\n\nReason codes: DOCUMENT_NOT_FOUND, DOCUMENT_VOID, RATE_LIMITED, API_DISABLED.", "tags": [ "Documents" ], "parameters": [ { "name": "no", "in": "path", "required": true, "description": "The short document number as printed.", "schema": { "type": "string", "example": "AB-LND26-4F2K7C" } } ], "security": [], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "document": { "type": "object", "description": "The public field set: short_number, document_number, status, mda, process_name, document_name, party_display, tcc_ref, issued_at, verify_url, sandbox and, where void, void_reason." } }, "required": [ "document" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/pvs": { "post": { "operationId": "createVoucherOnAuthority", "summary": "Raise a voucher against an award or payment authority number", "description": "The same act with the number in the body rather than the contract in the path. It takes an award number directly, and it is the only way to raise a voucher against a PAYMENT AUTHORITY — imprest, an advance, a non-contract payment. An authority is the final-document equivalent for those, so BR-14 holds here too.\n\n- Cumulative gross is checked against the authority's ceiling and its validity dates.\n\n- Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no voucher is raised meanwhile; the period is fixed at the moment of the request. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.\n\nScope: `pv`.\n\nReason codes: NOT_FOUND, PV_TCC_STALE, VALIDATION_ERROR, QUEUED_DEGRADED, SCOPE_MISSING, API_DISABLED.", "tags": [ "Vouchers" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "final_doc_no": { "type": "string", "description": "The award or authority number the voucher is drawn on. award_number is accepted as a synonym.", "example": "AB-AGT26-2M8P4D" }, "pv_type": { "type": "string", "description": "Which kind of payment this is.", "enum": [ "contract", "part", "retention", "adjustment", "imprest", "non_contract", "advance" ] }, "gross_amount": { "type": "number", "description": "Gross payable before deductions.", "example": 1250000 }, "description": { "type": "string", "description": "What is being paid for." }, "invoice_ref": { "type": "string", "description": "Supplier invoice reference." }, "period": { "type": "string", "description": "YYYY-MM the payment belongs to." } }, "required": [ "final_doc_no", "pv_type", "gross_amount" ], "example": { "final_doc_no": "AB-AGT26-2M8P4D", "pv_type": "non_contract", "gross_amount": 1250000, "description": "Quarterly office supplies" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "voucher": { "type": "object", "description": "As POST /contracts/{ref}/pvs returns it." }, "message": { "type": "string", "description": "What happens next." } }, "required": [ "voucher", "message" ], "description": "The result of this call." } } } } } }, "202": { "$ref": "#/components/responses/Queued" }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/pvs/{pv_no}": { "get": { "operationId": "getVoucher", "summary": "Read a payment voucher", "description": "The voucher with its deduction breakdown and its position in the approval chain. Once paid it carries the payment code — the one string that ties voucher, schedule line, covering letter, bank narration and credit note together (FR-7.16).\n\n- net_amount stays null until the voucher reaches TICKED, on this endpoint as everywhere else.\n\nScope: `pv`.\n\nReason codes: NOT_FOUND, SCOPE_MISSING, API_DISABLED.", "tags": [ "Vouchers" ], "parameters": [ { "name": "pv_no", "in": "path", "required": true, "description": "The voucher number.", "schema": { "type": "string", "example": "PV-PAR-2026-11010001-000318" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "voucher": { "type": "object", "description": "As POST /contracts/{ref}/pvs returns it, with each line's current tick state and the payment code once it is paid." } }, "required": [ "voucher" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/pvs/{pv_no}/validate": { "post": { "operationId": "validateVoucher", "summary": "Validate a draft voucher", "description": "Re-checks the clearance for the voucher's fiscal year — the entity and every director (BR-03/04) — recomputes the deduction lines and moves the voucher from DRAFT to VALIDATED. A clearance that is not current leaves it in DRAFT with the reason and a remediation link, so the voucher is never lost, only waiting.\n\n- A stale clearance is a REFUSAL that still carries data: data.voucher is the voucher as it stands (still DRAFT) and data.blocking names the subject.\n\n- Everything after this point — ticking, controller approval, warrant, treasury approval — is done by named officers in the consoles, because each step is a different person and SEC-8 will not let one credential be all of them.\n\nScope: `pv`.\n\nReason codes: NOT_FOUND, PV_TCC_STALE, TCC_EXPIRED, TCC_MISSING, DIRECTOR_NONCOMPLIANT, VALIDATION_ERROR, SCOPE_MISSING, API_DISABLED.", "tags": [ "Vouchers" ], "parameters": [ { "name": "pv_no", "in": "path", "required": true, "description": "The voucher number.", "schema": { "type": "string", "example": "PV-PAR-2026-11010001-000318" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "voucher": { "type": "object", "description": "The voucher after the check — status VALIDATED, or still DRAFT when the clearance is stale. net_amount is still null: the net is revealed at TICKED, not here." }, "message": { "type": "string", "description": "What happened, in a sentence." } }, "required": [ "voucher", "message" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/queue/{ref}": { "get": { "operationId": "getQueuedRequest", "summary": "Follow a request accepted in degraded mode", "description": "When a dependency the platform does not own is down, a submission, a document request, a payment citation, a voucher raise or a corporate registration is answered 202 QUEUED_DEGRADED with a queue reference instead of being judged. Queued is not approved: the request carries no verdict, and when service resumes it is processed through exactly the checks a live call goes through. This call says where it stands and, once it has been processed, what the answer was.\n\n- Any active key may call it, but a client sees only the requests IT queued, in its own environment. Another client's reference, a counter's, or one that does not exist is NOT_FOUND alike.\n\n- status: queued (waiting), draining (being processed now), done (the service answered — outcome.ok says whether it was accepted or refused), failed (it could not be processed at all; submit it again) or abandoned.\n\n- Do not issue, pay or act on a queued request. A document number, voucher number or party reference exists only once outcome carries one.\n\n- Prefer the queue.processed webhook to tight polling: the queue is drained every minute once the dependency has recovered. The webhook is sent for live requests only; in the sandbox, poll.\n\nReason codes: NOT_FOUND.", "tags": [ "Queue" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The queue reference from the 202 answer, QUE-YYYY-XXXXXX.", "schema": { "type": "string", "example": "QUE-2026-7K2M9P" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "queue_ref": { "type": "string", "description": "QUE-YYYY-XXXXXX." }, "kind": { "type": "string", "description": "What was queued.", "enum": [ "transaction_submit", "document_request", "payment_evidence", "pv_raise", "party_register" ] }, "status": { "type": "string", "description": "Where it stands.", "enum": [ "queued", "draining", "done", "failed", "abandoned" ] }, "message": { "type": "string", "description": "The position in a sentence, safe to show an officer. While queued it says not to issue the document." }, "subject_ref": { "type": "string", "description": "The case, award number or RC number the request is about; for a queued submission, the transaction reference once it has been opened.", "nullable": true }, "queued_at": { "type": "string", "description": "When it was accepted.", "nullable": true }, "next_attempt_at": { "type": "string", "description": "While queued: the earliest it will be looked at again.", "nullable": true }, "completed_at": { "type": "string", "description": "When it reached done, failed or abandoned.", "nullable": true }, "attempts": { "type": "integer", "description": "Processing attempts that could not complete. Waiting for a dependency uses none." }, "outcome": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True when the request was accepted." }, "outcome": { "type": "string", "description": "accepted, refused, failed or abandoned." }, "reason_code": { "type": "string", "description": "The published code when it was not accepted.", "nullable": true }, "message": { "type": "string", "description": "What the service said." }, "txn_ref": { "type": "string", "description": "The transaction, for a submission, document request or payment." }, "status": { "type": "string", "description": "The transaction status after a submission." }, "blocking": { "type": "array", "items": { "type": "object" }, "description": "Gates still blocking, when there are any." }, "doc_no": { "type": "string", "description": "The final document number, when one was issued." }, "doc_no_short": { "type": "string", "description": "Its short form." }, "validation": { "type": "string", "description": "The ledger's verdict on a payment reference." }, "pv_no": { "type": "string", "description": "The voucher number, when one was raised." }, "party_ref": { "type": "string", "description": "The party, for a registration.", "nullable": true } }, "description": "Null while queued or draining; afterwards, the service's answer.", "nullable": true }, "queue_url": { "type": "string", "description": "This resource." } }, "required": [ "queue_ref", "kind", "status", "message", "attempts", "queue_url" ], "description": "The result of this call." } }, "example": { "ok": true, "verification_id": "VRF-2026-9F3C1D7A4B2E", "timestamp": "2026-09-14T09:12:44+01:00", "request": { "id": "a71f3c9d2b40", "ip": "102.89.44.10", "client": "CLI-2026-004417", "mda": "20008001", "env": "sandbox", "echo": {} }, "data": { "queue_ref": "QUE-2026-7K2M9P", "kind": "document_request", "status": "done", "message": "Processed.", "subject_ref": "BTX-2026-004871", "queued_at": "2026-09-14 09:12:44", "next_attempt_at": null, "completed_at": "2026-09-14 09:41:02", "attempts": 0, "outcome": { "ok": true, "outcome": "accepted", "txn_ref": "BTX-2026-004871", "doc_no": "AB/LND/COFO/2026/4F2K7C/TCC-2026-004418", "doc_no_short": "AB-LND26-4F2K7C", "message": "Issued: AB/LND/COFO/2026/4F2K7C/TCC-2026-004418" }, "queue_url": "https://services.abiastate.gov.ng/api/v1/queue/QUE-2026-7K2M9P" } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/sandbox/identities": { "get": { "operationId": "sandboxIdentities", "summary": "Read the seeded identities", "description": "The same cast this portal publishes, from the sandbox itself — so a test harness can read it at run time instead of hard-coding what a page said.\n\nReason codes: SANDBOX_ONLY, API_DISABLED.", "tags": [ "Sandbox" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "identities": { "type": "array", "items": { "type": "object", "properties": { "abssin": { "type": "string", "description": "The state identification number, or null for the unregistered person.", "nullable": true }, "nin": { "type": "string", "description": "Set only on the identity that has no ABSSIN.", "nullable": true }, "kind": { "type": "string", "description": "individual, business_name or llc." }, "name": { "type": "string", "description": "Registered name." }, "rc_number": { "type": "string", "description": "CAC number, for the corporate identities.", "nullable": true }, "tcc": { "type": "string", "description": "What certificate this identity holds.", "enum": [ "current", "expired", "none" ] }, "directors": { "type": "array", "items": { "type": "string" }, "description": "The ABSSINs standing behind a corporate identity." }, "note": { "type": "string", "description": "What the identity is for." } }, "required": [ "kind", "name", "tcc", "directors", "note" ] }, "description": "The seeded parties." }, "process": { "type": "string", "description": "The sandbox process, as {AGENCY_CODE}/{PROCESS_CODE}.", "example": "LND/COFO" }, "note": { "type": "string", "description": "A reminder that a reset restores these identifiers and never renumbers them." } }, "required": [ "identities", "process", "note" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/sandbox/pay": { "post": { "operationId": "sandboxPay", "summary": "Settle a sandbox bill", "description": "Marks a sandbox bill settled so the gate that is waiting on it can clear. There is no payment gateway in the sandbox and nothing here reaches the collection ledger: this is the stand-in for a taxpayer paying, and a live key is refused.\n\n- It settles the assessment in full. There is no partial-payment parameter — to see a shortfall, work a case whose declared value exceeds the basis of the clearance held.\n\n- The reference to cite afterwards comes back as data.paid_ref.\n\nReason codes: SANDBOX_ONLY, NOT_FOUND, VALIDATION_ERROR, API_DISABLED.", "tags": [ "Sandbox" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "The bill reference the assessment carries, or the assessment reference itself. bill_ref and assessment_ref are accepted as synonyms.", "example": "SBX-BAS-000418" } }, "required": [ "reference" ], "example": { "reference": "SBX-BAS-000418" } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "reference": { "type": "string", "description": "As cited." }, "state": { "type": "string", "description": "The assessment chain state after settlement." }, "transaction_ref": { "type": "string", "description": "The case the bill belonged to.", "nullable": true }, "head": { "type": "string", "description": "The head settled.", "nullable": true }, "amount": { "type": "number", "description": "What was recorded as paid.", "nullable": true }, "paid_ref": { "type": "string", "description": "The sandbox payment reference. Cite this on /transactions/{ref}/payments.", "nullable": true }, "message": { "type": "string", "description": "What happened, in a sentence.", "nullable": true } }, "required": [ "reference", "state" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/sandbox/reset": { "post": { "operationId": "sandboxReset", "summary": "Reseed the sandbox", "description": "Removes the transactions, documents, contracts and vouchers the fixtures took part in and rebuilds the cast. The published ABSSINs themselves survive — they are documented, and your stored test data points at them. Three per hour, per client; it also runs nightly on its own.\n\n- The body is empty. There is no confirmation flag: the Idempotency-Key is what stops a retry resetting twice, and the throttle is what stops a loop.\n\n- Every transaction, document, contract and voucher you were holding is gone afterwards. That is the point: a test that depends on yesterday's data is not a test.\n\nReason codes: SANDBOX_ONLY, RATE_LIMITED, INTERNAL_ERROR, API_DISABLED.", "tags": [ "Sandbox" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "purged": { "type": "object", "description": "What was removed, counted by kind." }, "seeded": { "type": "object", "description": "What was rebuilt: parties, certificates, directorships, rates, thresholds, the process, and any warnings." }, "identities": { "type": "array", "items": { "type": "object" }, "description": "The cast now available, as GET /sandbox/identities returns it." } }, "required": [ "purged", "seeded", "identities" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/transactions": { "post": { "operationId": "createTransaction", "summary": "Submit a case and run the compliance gates", "description": "The machine twin of an officer capturing a case in the agency console. The platform resolves the party, pins the published version of the process, runs every configured gate and answers with the position. A blocked case names the gate, the subject and the remediation link; an eligible case is ready for a document.\n\n- The transaction is created whether or not it clears — you need the transaction_ref to pay and come back.\n\n- When a gate blocks, the answer is ok=false with the first blocking reason code and its remediation link, AND data still carries the whole transaction view. Read data even on a refusal.\n\n- declared_value is required for a value-bearing process; a value above the basis of the clearance held raises an automatic additional assessment (BR-08) rather than a silent pass.\n\n- The process must belong to the calling agency. Both a bare code (COFO) and the labelled form (LND/COFO) are accepted — anything before the last slash is discarded.\n\n- Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no case is opened and no gate runs until service resumes, so there is no transaction_ref yet; the processed queue entry carries it. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.\n\n- The queue never stores an identity number. A party named by NIN is queued by the party reference the platform already holds for that person; if it holds none, the call answers a retryable INTERNAL_ERROR — retry later, or name the party by abssin or party_ref.\n\nScope: `transact`.\n\nReason codes: PROCESS_NOT_CONFIGURED, PROCESS_MDA_MISMATCH, PARTY_NOT_FOUND, PARTY_NO_ABSSIN, VALUE_REQUIRED, TCC_MISSING, TCC_EXPIRED, TCC_STALE_FOR_YEAR, TCC_PENDING_VERIFICATION, DIRECTOR_NONCOMPLIANT, DIRECTOR_PENDING, PROPRIETOR_NONCOMPLIANT, CGT_UNPAID, CGT_SHORTFALL, STAMP_UNPAID, STAMP_SHORTFALL, FEE_UNPAID, VALUE_VARIANCE, GATE_PENDING, VALIDATION_ERROR, QUEUED_DEGRADED.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "process": { "type": "string", "description": "The configured process. process_code is accepted as a synonym.", "example": "LND/COFO" }, "party": { "type": "object", "properties": { "abssin": { "type": "string", "description": "State identification number." }, "nin": { "type": "string", "description": "National identity number." }, "rc": { "type": "string", "description": "CAC number." }, "tin": { "type": "string", "description": "Taxpayer identification number." }, "party_ref": { "type": "string", "description": "A party reference already issued." } }, "description": "One identifier, exactly as /parties/verify accepts. The same fields at the top level of the body also work." }, "declared_value": { "type": "number", "description": "Transaction value in naira. Required by value-bearing processes.", "example": 25000000 }, "instrument": { "type": "string", "description": "Stamp-duty instrument key where the process has one." }, "external_ref": { "type": "string", "description": "Your own case reference. Returned on every answer.", "example": "LND/2026/00821" }, "payload": { "type": "object", "description": "The process fields, keyed by field key. Validated against the published version." } }, "required": [ "process", "party" ], "example": { "process": "LND/COFO", "party": { "abssin": "SBX0000102" }, "declared_value": 25000000, "external_ref": "LND/2026/00821", "payload": { "instrument": "deed_of_assignment", "property_address": "Plot U/1147, Umuahia North" } } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "transaction_ref": { "type": "string", "description": "BTX-YYYY-XXXXXX. Cite it on every later call." }, "status": { "type": "string", "description": "blocked = at least one applicable gate is not terminal (BR-01).", "enum": [ "draft", "submitted", "blocked", "eligible", "issuing", "issued", "void", "cancelled" ] }, "mda": { "type": "string", "description": "The agency the case belongs to." }, "process": { "type": "string", "description": "The process code.", "nullable": true }, "process_name": { "type": "string", "description": "What the process issues.", "nullable": true }, "party": { "type": "object", "properties": { "party_ref": { "type": "string", "description": "BPR-YYYY-XXXXXX." }, "display_name": { "type": "string", "description": "Registered name." }, "kind": { "type": "string", "description": "Entity type." }, "abssin": { "type": "string", "description": "State identification number.", "nullable": true } }, "required": [ "party_ref", "display_name", "kind" ], "description": "The resolved party.", "nullable": true }, "declared_value": { "type": "number", "description": "As submitted.", "nullable": true }, "instrument": { "type": "string", "description": "As submitted.", "nullable": true }, "external_ref": { "type": "string", "description": "Your own reference, echoed.", "nullable": true }, "gates": { "type": "array", "items": { "type": "object", "properties": { "gate": { "type": "string", "description": "TCC, CGT, STAMP, FEE or BR — the head this gate guards." }, "status": { "type": "string", "description": "Upper case, as the register holds it. CLEARED and NOT_APPLICABLE are terminal; everything else stands in the way.", "enum": [ "CLEARED", "ASSESSED", "SHORTFALL", "PENDING", "NOT_APPLICABLE" ] }, "subject": { "type": "string", "description": "Who the gate is about, when it is not the entity.", "nullable": true }, "role": { "type": "string", "description": "Whose position this gate is about.", "enum": [ "entity", "business_name", "director", "proprietor" ], "nullable": true }, "reason_code": { "type": "string", "description": "The published code for a gate that is not cleared.", "nullable": true }, "computed_amount": { "type": "number", "description": "What the rules say is due on this head.", "nullable": true }, "paid_amount": { "type": "number", "description": "What has been matched against it.", "nullable": true }, "na_reason": { "type": "string", "description": "Why the gate does not apply.", "nullable": true }, "evaluated_at": { "type": "string", "description": "When it was last judged.", "nullable": true } }, "required": [ "gate", "status" ] }, "description": "Every gate the process applies." }, "blocking": { "type": "array", "items": { "type": "object", "properties": { "gate": { "type": "string", "description": "The gate." }, "status": { "type": "string", "description": "Its status.", "nullable": true }, "reason_code": { "type": "string", "description": "A published reason code.", "nullable": true }, "subject": { "type": "string", "description": "Who is failing — the entity or the director by name.", "nullable": true }, "role": { "type": "string", "description": "Their role.", "nullable": true }, "amount_due": { "type": "number", "description": "What is payable to clear it.", "nullable": true }, "assessment_ref": { "type": "string", "description": "The assessment raised for it.", "nullable": true }, "message": { "type": "string", "description": "Renderable message with the subject named.", "nullable": true } }, "required": [ "gate" ] }, "description": "The gates standing in the way, with a readable message each." }, "assessments": { "type": "array", "items": { "type": "object", "properties": { "reference": { "type": "string", "description": "The assessment reference." }, "head": { "type": "string", "description": "Revenue head assessed." }, "basis": { "type": "string", "description": "The frozen sentence explaining how the figure was reached." }, "computed": { "type": "number", "description": "What the rules computed." }, "paid_before": { "type": "number", "description": "What had already been paid on this head." }, "amount_due": { "type": "number", "description": "The balance payable." }, "state": { "type": "string", "description": "Where the assessment sits in the chain.", "enum": [ "raised", "director_review", "chairman_review", "approved", "rejected", "billed", "paid", "cancelled" ] }, "bill_ref": { "type": "string", "description": "The bill reference in the collection ledger.", "nullable": true }, "pay_url": { "type": "string", "description": "A link the taxpayer can pay from. Always null in the sandbox, which has no gateway — use POST /sandbox/pay.", "nullable": true }, "paid_ref": { "type": "string", "description": "The payment reference that settled it.", "nullable": true } }, "required": [ "reference", "head", "basis", "computed", "paid_before", "amount_due", "state" ] }, "description": "Bills raised by the gates." }, "document": { "type": "object", "description": "Present once issued: document_number, short_number, status, tcc_ref, issued_at, verification_id, verify_url.", "nullable": true }, "remediation_url": { "type": "string", "description": "Added when the case is blocked: a single-use page the taxpayer can open.", "nullable": true }, "created_at": { "type": "string", "description": "When the case was opened.", "nullable": true } }, "required": [ "transaction_ref", "status", "mda", "gates", "blocking", "assessments" ], "description": "The result of this call." } }, "example": { "ok": true, "verification_id": "VRF-2026-9F3C1D7A4B2E", "timestamp": "2026-09-14T09:12:44+01:00", "request": { "id": "a71f3c9d2b40", "ip": "102.89.44.10", "client": "CLI-2026-004417", "mda": "20008001", "env": "sandbox", "echo": {} }, "data": { "transaction_ref": "BTX-2026-004871", "status": "blocked", "mda": "20008001", "process": "COFO", "process_name": "Certificate of Occupancy (sandbox)", "party": { "party_ref": "BPR-2026-000914", "display_name": "Sandbox Blocked Ventures Limited", "kind": "llc", "abssin": "SBX0000102" }, "declared_value": 25000000, "instrument": "deed_of_assignment", "external_ref": "LND/2026/00821", "gates": [ { "gate": "TCC", "status": "PENDING", "subject": "Uche Sandbox Nocert", "role": "director", "reason_code": "DIRECTOR_NONCOMPLIANT", "computed_amount": null, "paid_amount": null, "na_reason": null, "evaluated_at": "2026-09-14T09:12:44+01:00" }, { "gate": "CGT", "status": "ASSESSED", "subject": null, "role": "entity", "reason_code": "CGT_UNPAID", "computed_amount": 2500000, "paid_amount": 0, "na_reason": null, "evaluated_at": "2026-09-14T09:12:44+01:00" } ], "blocking": [ { "gate": "TCC", "status": "PENDING", "reason_code": "DIRECTOR_NONCOMPLIANT", "subject": "Uche Sandbox Nocert", "role": "director", "amount_due": null, "assessment_ref": null, "message": "Director Uche Sandbox Nocert has no current tax clearance certificate." } ], "assessments": [ { "reference": "ASM-2026-011204", "head": "CGT", "basis": "10% of 25,000,000.00 declared value, rate card 2026-01-01", "computed": 2500000, "paid_before": 0, "amount_due": 2500000, "state": "raised", "bill_ref": "SBX-BAS-000418", "pay_url": null, "paid_ref": null } ], "document": null, "remediation_url": "https://services.abiastate.gov.ng/remediate/9f3c1d7a4b2e" } } } } } }, "202": { "$ref": "#/components/responses/Queued" }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/transactions/{ref}": { "get": { "operationId": "getTransaction", "summary": "Read a transaction and its current gate position", "description": "The same body as the submission, as the register holds it now. Poll this after your taxpayer pays if you have not subscribed to transaction.gate_changed — settlement is discovered by a sweep, so a gate can clear minutes after the money moves.\n\n- A transaction belonging to another agency is a not-found, not a forbidden: an integrator may not enumerate another agency's cases.\n\nScope: `transact`.\n\nReason codes: NOT_FOUND, SCOPE_MISSING.", "tags": [ "Transactions" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The transaction reference, BTX-YYYY-XXXXXX.", "schema": { "type": "string", "example": "BTX-2026-004871" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "transaction_ref": { "type": "string", "description": "The transaction reference." }, "status": { "type": "string", "description": "Current status." }, "gates": { "type": "array", "items": { "type": "object" }, "description": "As on submission." }, "blocking": { "type": "array", "items": { "type": "object" }, "description": "As on submission." }, "assessments": { "type": "array", "items": { "type": "object" }, "description": "As on submission." }, "document": { "type": "object", "description": "Present once issued.", "nullable": true } }, "required": [ "transaction_ref", "status", "gates", "blocking", "assessments" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/transactions/{ref}/assessments": { "post": { "operationId": "raiseAssessment", "summary": "Re-run the gates and read everything that is owed", "description": "Re-evaluates the case against the rules as they stand now and hands back what the party owes on every head, with the bill reference and the payment link for each (FR-4.6, FR-11.2). The platform computes every figure from the effective rate card and freezes the basis: a caller never supplies an amount, because a figure supplied by the payer is not an assessment.\n\n- It is a POST because it re-evaluates: a certificate may have been issued, a bill settled or a rate corrected since the last look.\n\n- The body is empty. There is no per-head parameter — the gates decide which heads apply.\n\n- An amount above the automatic ceiling is routed to an assessment officer and the gate reads ASSESSMENT_PENDING_APPROVAL — retryable, not a failure.\n\nScope: `transact`.\n\nReason codes: NOT_FOUND, ASSESSMENT_PENDING_APPROVAL, PROCESS_NOT_CONFIGURED, GATE_PENDING, VALIDATION_ERROR.", "tags": [ "Transactions" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The transaction reference.", "schema": { "type": "string", "example": "BTX-2026-004871" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "transaction_ref": { "type": "string", "description": "The transaction." }, "status": { "type": "string", "description": "Status after the re-run." }, "gates": { "type": "array", "items": { "type": "object" }, "description": "The recomputed gate list." }, "assessments": { "type": "array", "items": { "type": "object" }, "description": "Every assessment, each with its frozen basis, bill reference and payment link." }, "blocking": { "type": "array", "items": { "type": "object" }, "description": "What still stands in the way." } }, "required": [ "transaction_ref", "status", "gates", "assessments", "blocking" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/transactions/{ref}/document": { "post": { "operationId": "issueDocument", "summary": "Issue the final document", "description": "Mints the final document number for an eligible transaction (FR-5). The number embeds the tax clearance it was issued against, so the document can never be separated from the compliance that earned it. Refused while any applicable gate is open; asking twice returns the same number, never a second one.\n\n- The body is empty: the issuing system is taken from the key, not from the request.\n\n- Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no number is minted meanwhile, and none may be written on a document. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.\n\n- A refusal carries data.blocking — the gates that are still open — so one call tells you both that it did not issue and what to do about it.\n\nScope: `documents`.\n\nReason codes: GATE_PENDING, TCC_MISSING, TCC_EXPIRED, NOT_FOUND, QUEUED_DEGRADED, VALIDATION_ERROR.", "tags": [ "Transactions" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The transaction reference.", "schema": { "type": "string", "example": "BTX-2026-004871" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "document": { "type": "object", "properties": { "document_number": { "type": "string", "description": "The long form: AB/{MDA}/{PROC}/{YYYY}/{SEQ}/{TCC-REF}." }, "short_number": { "type": "string", "description": "The addressable short form printed on the document." }, "status": { "type": "string", "description": "Status on the register.", "enum": [ "valid", "void" ] }, "tcc_ref": { "type": "string", "description": "The clearance the number embeds." }, "tcc_valid_until": { "type": "string", "description": "Expiry of that clearance.", "nullable": true }, "issued_at": { "type": "string", "description": "Issue timestamp, ISO-8601." }, "verification_id": { "type": "string", "description": "The ledger id for the issuance itself." }, "verify_url": { "type": "string", "description": "The public verification page — the same target as the QR code." }, "void_reason": { "type": "string", "description": "Why it was voided, when it has been.", "nullable": true } }, "required": [ "document_number", "short_number", "status", "tcc_ref", "issued_at", "verification_id", "verify_url" ], "description": "The minted document." } }, "required": [ "document" ], "description": "The result of this call." } }, "example": { "ok": true, "verification_id": "VRF-2026-9F3C1D7A4B2E", "timestamp": "2026-09-14T09:12:44+01:00", "request": { "id": "a71f3c9d2b40", "ip": "102.89.44.10", "client": "CLI-2026-004417", "mda": "20008001", "env": "sandbox", "echo": {} }, "data": { "document": { "document_number": "AB/LND/COFO/2026/4F2K7C/TCC-2026-004418", "short_number": "AB-LND26-4F2K7C", "status": "valid", "tcc_ref": "TCC/2026/004418", "tcc_valid_until": "2026-12-31", "issued_at": "2026-09-14T10:02:11+01:00", "verification_id": "VRF-2026-9F3C1D7A4B2E", "verify_url": "https://services.abiastate.gov.ng/verify/document/AB-LND26-4F2K7C", "void_reason": null } } } } } } }, "202": { "$ref": "#/components/responses/Queued" }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/transactions/{ref}/payments": { "post": { "operationId": "citePayment", "summary": "Cite a payment against a transaction", "description": "Tells the platform that a reference in the central collection ledger belongs to this transaction and this head. Nothing is taken on trust: the reference must exist, be settled, belong to this taxpayer, sit under the right revenue head and not already have been spent on another case.\n\n- Gates are re-run immediately, so data.transaction already shows whether the payment cleared the gate.\n\n- A refusal still returns data, carrying matched=false and the ledger's own verdict in data.validation.\n\n- Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — the reference is neither matched nor refused until the ledger can be read. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.\n\nScope: `pay`.\n\nReason codes: PAYMENT_REF_UNKNOWN, PAYMENT_NOT_SETTLED, PAYMENT_AMOUNT_MISMATCH, PAYMENT_PARTY_MISMATCH, PAYMENT_HEAD_MISMATCH, PAYMENT_DUPLICATE, NOT_FOUND, VALIDATION_ERROR, QUEUED_DEGRADED.", "tags": [ "Transactions" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The transaction reference.", "schema": { "type": "string", "example": "BTX-2026-004871" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "The payment reference from the collection ledger or the receipt. At most 80 characters.", "example": "ABP-2026-77120043" }, "head": { "type": "string", "description": "Which gate the payment is offered against.", "enum": [ "CGT", "STAMP", "FEE", "TCC" ], "example": "CGT" }, "amount": { "type": "number", "description": "What you believe was paid. A disagreement with the ledger is refused, not reconciled." } }, "required": [ "reference", "head" ], "example": { "reference": "ABP-2026-77120043", "head": "CGT", "amount": 2500000 } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "matched": { "type": "boolean", "description": "Whether the evidence was accepted." }, "head": { "type": "string", "description": "The head it was applied to." }, "reference": { "type": "string", "description": "The reference as cited." }, "message": { "type": "string", "description": "What the evidence service made of it.", "nullable": true }, "transaction": { "type": "object", "description": "The whole transaction view after re-running the gates — status, gates, blocking, assessments." } }, "required": [ "matched", "head", "reference", "transaction" ], "description": "The result of this call." } } } } } }, "202": { "$ref": "#/components/responses/Queued" }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List your subscriptions", "description": "Every endpoint registered by this client, with its health. A subscription paused after repeated failures shows here with its failure count before it shows anywhere else.\n\nScope: `webhooks`.\n\nReason codes: SCOPE_MISSING.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Subscription id." }, "url": { "type": "string", "description": "Delivery URL." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Events subscribed." }, "status": { "type": "string", "description": "paused = too many consecutive failures.", "enum": [ "active", "paused", "disabled" ] }, "consecutive_failures": { "type": "integer", "description": "Failures since the last success." }, "paused_after": { "type": "integer", "description": "The failure count at which the platform pauses the endpoint." }, "last_success_at": { "type": "string", "description": "Last accepted delivery.", "nullable": true }, "created_at": { "type": "string", "description": "When it was registered.", "nullable": true } }, "required": [ "id", "url", "events", "status", "consecutive_failures", "paused_after" ] }, "description": "The subscriptions." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Every event name this platform will accept in a subscription." }, "queue_due": { "type": "integer", "description": "Deliveries waiting to go out across the platform." }, "signature_note": { "type": "string", "description": "The signing string, restated so a client can be written from this response alone." } }, "required": [ "webhooks", "events", "queue_due", "signature_note" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } }, "post": { "operationId": "createWebhook", "summary": "Subscribe to events", "description": "Registers an HTTPS endpoint and returns the signing secret ONCE. Store it: it is encrypted at rest and cannot be shown again. The URL must be https, must resolve to a public address, and must not redirect — a loopback or private host is refused outright.\n\n- Subscribe to the events you handle. An event you did not ask for is never sent, and an unknown event name is a validation error rather than a silent no-op.\n\n- One client may hold ten endpoints. Delete one before registering an eleventh.\n\nScope: `webhooks`.\n\nReason codes: VALIDATION_ERROR, SCOPE_MISSING.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS endpoint on a public host, at most 255 characters, no credentials in the URL, port 443 or above 1024.", "example": "https://lands.example.gov.ng/hooks/abia" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event names from the published list.", "example": [ "transaction.gate_changed", "document.issued" ] } }, "required": [ "url", "events" ], "example": { "url": "https://lands.example.gov.ng/hooks/abia", "events": [ "transaction.gate_changed", "document.issued" ] } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "description": "The subscription as registered: id, url, events, status, consecutive_failures, paused_after, created_at." }, "secret": { "type": "string", "description": "The signing secret. Shown once, never again." }, "notice": { "type": "string", "description": "A reminder to store the secret before closing the response." } }, "required": [ "webhook", "secret", "notice" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Read one subscription", "description": "The subscription with its recent delivery history: what was sent, what your endpoint answered, and when the next attempt is due. The first place to look when events have stopped arriving.\n\n- The secret is never returned. If you have lost it, delete the subscription and register it again.\n\nScope: `webhooks`.\n\nReason codes: NOT_FOUND, SCOPE_MISSING.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string", "example": "17" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "description": "The subscription, as in the list." }, "deliveries": { "type": "array", "items": { "type": "object" }, "description": "The fifty most recent deliveries: id, event, status, attempts, the last HTTP code and when the next attempt is due." } }, "required": [ "webhook", "deliveries" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } }, "delete": { "operationId": "deleteWebhook", "summary": "Stop a subscription", "description": "Stops delivery. The subscription is DISABLED rather than erased, so its delivery history — which is the evidence in a \"we never received it\" conversation — survives, and POST /webhooks/{id}/enable can bring it back without reconfiguring anything.\n\n- Events already queued for it are kept but never sent while it is disabled.\n\nScope: `webhooks`.\n\nReason codes: NOT_FOUND, SCOPE_MISSING.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string", "example": "17" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "description": "The subscription, now status disabled." }, "message": { "type": "string", "description": "What was done." } }, "required": [ "webhook", "message" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/webhooks/{id}/enable": { "post": { "operationId": "enableWebhook", "summary": "Resume a paused or disabled subscription", "description": "Clears the failure count and puts the subscription back to active. Use it once your endpoint is answering again — the platform pauses rather than deletes, so nothing has to be reconfigured. The URL is re-checked against the SSRF rules first: a name that now resolves to a private address is refused.\n\n- Resuming does not resend what was already marked dead; use the redeliver endpoint for that.\n\nScope: `webhooks`.\n\nReason codes: NOT_FOUND, VALIDATION_ERROR, SCOPE_MISSING.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string", "example": "17" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "description": "The subscription, now active with consecutive_failures reset to zero." }, "message": { "type": "string", "description": "What happens next." } }, "required": [ "webhook", "message" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } }, "/webhooks/{id}/redeliver": { "post": { "operationId": "redeliverWebhook", "summary": "Send one failed delivery again", "description": "Puts a single failed or dead delivery back at the front of the queue, so an outage on your side does not cost you the event it spanned. It goes out with its original delivery id, so your deduplication still holds.\n\n- One delivery per call: name it. Read GET /webhooks/{id} for the ids of the deliveries that failed.\n\n- A delivery that is not failed or dead is refused with VALIDATION_ERROR naming its current status — a delivered event is not resent.\n\nScope: `webhooks`.\n\nReason codes: NOT_FOUND, VALIDATION_ERROR, SCOPE_MISSING.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string", "example": "17" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SignatureTimestamp" }, { "$ref": "#/components/parameters/Signature" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "integer", "description": "The delivery to send again. It must belong to this subscription.", "example": 4417 } }, "required": [ "delivery_id" ], "example": { "delivery_id": 4417 } } } } }, "responses": { "200": { "description": "The answer. ok=true and the result in data.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verification_id", "timestamp", "request", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "True on a favourable answer." }, "verification_id": { "type": "string", "description": "The ledger id for this answer. A payment must cite it (SEC-5)." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "data": { "type": "object", "properties": { "delivery_id": { "type": "integer", "description": "The delivery requeued." }, "status": { "type": "string", "description": "pending." }, "message": { "type": "string", "description": "When it goes out." } }, "required": [ "delivery_id", "status", "message" ], "description": "The result of this call." } } } } } }, "default": { "$ref": "#/components/responses/Refused" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer {key_id}.{secret}. key_id is ak_live_… or ak_sbx_…; the secret is shown once when the key is issued and is stored only as a peppered hash." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Up to 64 characters of [A-Za-z0-9_-:.]. A retry with the same key and the same body replays the stored answer; the same key with a different body is refused.", "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_\\-:.]+$" } }, "SignatureTimestamp": { "name": "X-Timestamp", "in": "header", "required": false, "description": "Unix seconds. Required when the client is configured to sign; ±300 s skew.", "schema": { "type": "integer" } }, "Signature": { "name": "X-Signature", "in": "header", "required": false, "description": "v1=hex(hmac_sha256(secret, ts \\n METHOD \\n path \\n sha256(body))). Required when the client is configured to sign.", "schema": { "type": "string" } } }, "headers": { "XRequestId": { "description": "Correlation id for this call. Quote it in support.", "schema": { "type": "string" } }, "RateLimitLimit": { "description": "Requests per minute allowed for this client.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "IdempotentReplayed": { "description": "Present and true when the body is a replay of an earlier identical call.", "schema": { "type": "string" } }, "ContentSha256": { "description": "Hex sha256 of the body sent, equal to the manifest entry.", "schema": { "type": "string" } }, "ExtractRows": { "description": "JSON lines in the file, as the manifest records.", "schema": { "type": "integer" } } }, "schemas": { "RequestMeta": { "type": "object", "description": "What the platform understood the call to be.", "properties": { "id": { "type": "string", "description": "Request correlation id." }, "ip": { "type": "string", "description": "Address the call came from." }, "client": { "type": "string", "nullable": true, "description": "Calling client reference." }, "mda": { "type": "string", "nullable": true, "description": "Agency the key is scoped to." }, "env": { "type": "string", "nullable": true, "enum": [ "live", "sandbox" ], "description": "Environment the key belongs to." }, "echo": { "type": "object", "description": "Selected request fields echoed back." } } }, "Error": { "type": "object", "description": "A refusal. The code is drawn from the published catalogue and never renamed.", "required": [ "code", "title", "message", "retryable" ], "properties": { "code": { "type": "string", "description": "Published reason code." }, "title": { "type": "string", "description": "Short title for the code." }, "message": { "type": "string", "description": "Message with the subject filled in, safe to show an officer." }, "remediation_url": { "type": "string", "nullable": true, "description": "A page the taxpayer can open and act on." }, "retryable": { "type": "boolean", "description": "Whether the identical call may succeed later." }, "details": { "type": "object", "description": "Structured detail behind the message." } } }, "QueuedEnvelope": { "type": "object", "required": [ "ok", "timestamp", "request", "error", "data" ], "properties": { "ok": { "type": "boolean", "enum": [ false ], "description": "False: the request has not been answered yet." }, "verification_id": { "type": "string", "nullable": true, "description": "The ledger id for this acceptance." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "error": { "$ref": "#/components/schemas/Error" }, "data": { "type": "object", "description": "The queued request, as GET /queue/{ref} shows it.", "required": [ "queue_ref", "kind", "status", "message", "queue_url" ], "properties": { "queue_ref": { "type": "string", "description": "QUE-YYYY-XXXXXX.", "example": "QUE-2026-7K2M9P" }, "kind": { "type": "string", "enum": [ "transaction_submit", "document_request", "payment_evidence", "pv_raise", "party_register" ], "description": "What was queued." }, "status": { "type": "string", "enum": [ "queued", "draining", "done", "failed", "abandoned" ], "description": "queued on a first answer. A retry with the same Idempotency-Key replays this answer as it was sent; GET queue_url for where the request stands now." }, "message": { "type": "string", "description": "Says not to issue the document meanwhile." }, "subject_ref": { "type": "string", "nullable": true, "description": "The case, award number or RC number the request is about." }, "queued_at": { "type": "string", "nullable": true, "description": "When it was accepted." }, "attempts": { "type": "integer", "description": "Processing attempts so far." }, "outcome": { "type": "object", "nullable": true, "description": "Null until processed." }, "queue_url": { "type": "string", "description": "GET /queue/{ref}." }, "existing": { "type": "boolean", "description": "True when this Idempotency-Key had already queued the same request." } } } } }, "ErrorEnvelope": { "type": "object", "required": [ "ok", "timestamp", "request", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ], "description": "Always false here." }, "verification_id": { "type": "string", "nullable": true, "description": "Null when the call was refused before it became a verification." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time." }, "request": { "$ref": "#/components/schemas/RequestMeta" }, "error": { "$ref": "#/components/schemas/Error" }, "data": { "type": "object", "description": "Present on refusals that still produced state, e.g. a blocked transaction with its reference." } } } }, "responses": { "Queued": { "description": "QUEUED_DEGRADED: accepted in degraded mode and held, not judged. Nothing was issued, raised, matched or opened. Follow data.queue_url.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedEnvelope" } } } }, "Refused": { "description": "Refused. Read error.code; the envelope is authoritative even when the HTTP status is not.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "x-reason-codes": [ "API_DISABLED", "ASSESSMENT_PENDING_APPROVAL", "AUTH_INVALID", "BR_MISSING", "CGT_SHORTFALL", "CGT_UNPAID", "CLIENT_SUSPENDED", "CONTRACT_NOT_FOUND", "DIRECTOR_NONCOMPLIANT", "DIRECTOR_PENDING", "DOCUMENT_NOT_FOUND", "DOCUMENT_VOID", "FEE_UNPAID", "GATE_PENDING", "IDEMPOTENCY_EXPIRED", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "INTERNAL_ERROR", "IP_NOT_ALLOWED", "NOT_FOUND", "PARTY_NOT_FOUND", "PARTY_NO_ABSSIN", "PARTY_UNREGISTERED", "PAYMENT_AMOUNT_MISMATCH", "PAYMENT_DUPLICATE", "PAYMENT_HEAD_MISMATCH", "PAYMENT_NOT_SETTLED", "PAYMENT_NO_VERIFICATION", "PAYMENT_PARTY_MISMATCH", "PAYMENT_REF_UNKNOWN", "PROCESS_MDA_MISMATCH", "PROCESS_NOT_CONFIGURED", "PROPRIETOR_NONCOMPLIANT", "PV_TCC_STALE", "QUEUED_DEGRADED", "RATE_LIMITED", "SANDBOX_ONLY", "SCOPE_MISSING", "SIGNATURE_INVALID", "SIGNATURE_SKEW", "STAMP_SHORTFALL", "STAMP_UNPAID", "TCC_EXPIRED", "TCC_MISSING", "TCC_PENDING_VERIFICATION", "TCC_STALE_FOR_YEAR", "TLS_REQUIRED", "TOO_LARGE", "VALIDATION_ERROR", "VALUE_REQUIRED", "VALUE_VARIANCE" ], "x-webhook-events": { "party.registered": "A party was registered and given an ABSSIN.", "transaction.gate_changed": "A gate on a transaction moved; the payload carries the new blocking set.", "assessment.raised": "An assessment was raised, with its bill reference and payment link.", "assessment.approved": "An assessment above the automatic ceiling was approved by an officer.", "payment.confirmed": "A cited payment was matched and settled in the central ledger.", "document.issued": "A final document number was minted.", "document.voided": "A final document was voided, with the reason.", "contract.awarded": "A contract passed its gates and was awarded; the award number is the document number.", "pv.status_changed": "A payment voucher moved through the approval chain — raised, validated, ticked, approved, warranted.", "pv.paid": "A payment voucher was paid, with its payment code and the verification id behind it (FR-11.5).", "queue.processed": "A request accepted in degraded mode was finally processed.", "api.deprecation_notice": "An endpoint your client uses has a sunset date.", "sandbox.reset": "The sandbox was reseeded; your test references are gone." }, "x-sandbox-identities": [ { "ref": "SBX0000001", "kind": "Individual", "state": "Compliant", "detail": "Current tax clearance for the running year. The happy path." }, { "ref": "SBX0000002", "kind": "Individual", "state": "Expired", "detail": "Clearance expired last year — expect TCC_STALE_FOR_YEAR or TCC_EXPIRED with a remediation link." }, { "ref": "SBX0000101", "kind": "Limited company", "state": "Compliant", "detail": "Company and every director current. VAT registered, so VAT is withheld on its vouchers (BR-16)." }, { "ref": "SBX0000102", "kind": "Limited company", "state": "Blocked", "detail": "One director is not compliant — expect DIRECTOR_NONCOMPLIANT naming SBX0000013 (BR-10, acceptance 7)." }, { "ref": "SBX0000013", "kind": "Individual", "state": "Blocked", "detail": "The failing director of SBX0000102. Holds no clearance at all." }, { "ref": "SBX0000201", "kind": "Business name", "state": "Compliant", "detail": "Sole proprietorship — the proprietor is checked, not directors (BR-11)." }, { "ref": "99900000001", "kind": "NIN, no ABSSIN", "state": "Unregistered", "detail": "A person the register does not hold — expect PARTY_NO_ABSSIN, then register and retry." } ] }