Key Concepts & Glossary

qbill's API is meaningless without NRS's vocabulary first. This page defines the terms used throughout the rest of the documentation.

NRS vs. FIRS

The regulator is now the NRS (Nigeria Revenue Service), formerly FIRS (Federal Inland Revenue Service), under the Nigeria Tax Administration Act 2025. The e-invoicing program is the E-Invoicing & Electronic Fiscal System (EFS), commonly called the Merchant-Buyer Solution (MBS). You may still see firs* in older references — the two names refer to the same regulator.

Glossary

IRN: Invoice Reference Number — the unique identifier NRS assigns on clearance. It's embedded in the invoice and encoded into the QR code.
CSID: Cryptographic Stamp Identifier — NRS's own stamp of clearance, issued on successful validation. It is not something you generate yourself; that's the outbound signature (below).
Signature: Your own ECDSA signing of the outbound payload, applied before submission. Distinct from the CSID NRS returns afterward — don't describe an invoice as "signed by NRS"; NRS stamps it, you sign it.
Clearance / CTC: Continuous Transaction Control — NRS's pre-clearance model. An invoice is validated by NRS in real time, before or as it's issued, rather than reported after the fact.
Four-corner model: The supplier's system (corner 1) transmits via an Access Point Provider (corner 2) to NRS, which validates and stamps the invoice; the cleared invoice is then delivered to the buyer (corner 3) through their own access point (corner 4).
System Integrator (SI): Connects a taxpayer's own systems — ERP, accounting software — to the NRS platform. qbill holds this role for its customers.
Access Point Provider (APP): Transmits and receives invoices on a taxpayer's behalf, including digital signing and gateway communication. qbill holds this role too.
B2B / B2C / B2G: Business-to-business, business-to-consumer and business-to-government invoice kinds. B2B/B2G are pre-cleared before issuance; B2C follows a separate post-audit model (see Compliance Context).
UBL 2.1 / PEPPOL BIS Billing 3.0: The mandated document format and profile — XML or JSON, transmitted over TLS 1.3 — that every submitted invoice is transformed into.

Invoice lifecycle

Transitions are enforced — attempting to move an invoice somewhere the lifecycle forbids fails validation.

lifecycle

draft ──────────► pending_clearance ──► cleared      (B2B/B2G)
  │                      │
  ├──────────────► submitted                         (B2C, within the window)
  │                      │
  ├──► rejected ◄────────┘
  │        │
  │        └──► draft / pending_clearance / submitted   (correct & resubmit)
  │
  └──► cancelled

cleared, submitted and cancelled are terminal. An invoice in one of those states carries an NRS-issued IRN and is a statutory record — it can't be edited or resubmitted. Adjust it with a credit or debit note instead, which must reference the original invoice's IRN.