Nigeria 🇳🇬

E-invoicing through the Nigeria Revenue Service (NRS) Merchant Buyer Solution (NRSMBS) — formerly the FIRS Merchant Buyer Solution (FIRS MBS). This page is the API documentation for the Nigeria e-invoicing endpoints of the platform: every endpoint, the exact request and response payloads, how the IRN and QR code are produced, and how the platform maps onto the NRSMBS APIs.

Overview

Aspect	Details
Tax authority	Nigeria Revenue Service (NRS) — formerly Federal Inland Revenue Service (FIRS)
National platform	NRS Merchant Buyer Solution (NRSMBS) — einvoice.nrs.gov.ng
Model	Clearance (continuous transaction control): every invoice is validated and signed by NRSMBS before it is issued; NRS registers the IRN and the invoice carries a verifiable QR code
Service-provider roles	System Integrator (SI) — integrates taxpayer systems (validate, sign, IRN, QR); Access Point Provider (APP) — transmits and receives e-invoices between parties. The platform is operated in both roles.
Taxpayer identifier	TIN (Taxpayer Identification Number); each business also receives an 8-character NRS Service ID and a business_id (UUID) on onboarding
Invoice reference	IRN — <invoice number>-<Service ID>-<YYYYMMDD>, e.g. INV0706-39EADBB3-20260706 (unique per business per day)
Document format	NRS invoice JSON (UBL-aligned field names) — not Peppol UBL XML
Invoice kinds	invoice_kind = B2B, B2C or B2G (mandatory since December 2025)
VAT	7.5 % standard rate — tax category STANDARD_VAT; other categories per NRS code lists (exempt, zero-rated, withholding, stamp duty)
Line classification	Every invoice line needs an hsn_code (goods) or an isic_code (services)
QR code	Mandatory — RSA-encrypted { irn: "<IRN>.<unix ts>", certificate } using the NRS public key of the supplier business; verifiable through NRS verify_stamp and the MBS360 mobile app
Environments	Sandbox base_url https://eivc-k6z6d.ondigitalocean.app · report/exchange https://api.firsmbs.com · production URLs as issued in the NRS service-provider portal
NRS API docs	einvoice.nrs.gov.ng/docs (authentication, invoice schema, QR code, changelog)

Where the endpoints live

All Nigeria endpoints are under {BASE_URL}/api/v1/nigeria/… on your platform host — for example https://einvoicing.huiospay.com/peppol-api/api/v1/nigeria/validate on the HuiosPay-branded platform, or https://app.goroute.ai/peppol-api/api/v1/nigeria/validate on GoRoute. The live OpenAPI contract is served at {BASE_URL}/docs (Swagger UI) and {BASE_URL}/openapi.json.

How an e-invoice flows

Taxpayer system ─1─▶ POST /api/v1/nigeria/validate {invoice, sign:true}
                       │  2  POST base_url/api/v1/invoice/validate  ──▶ NRSMBS  (200 ok)
                       │  3  POST base_url/api/v1/invoice/sign      ──▶ NRSMBS  (201 ok, IRN registered)
                       │  4  build QR  = RSA(NRS public key){ irn: IRN.<ts>, certificate }
                       │  5  persist invoice · IRN · QR · NRS responses · render PDF/JSON
                ◀─6─── 201 { ok:true, signed:true, transaction_id … }  +  POST /qr → QR image

Platform (worker, APP role) ─7─▶ confirm / download (AES-256-CFB decrypt)
                            ─8─▶ transmit to counterparties  ◀─9─ NRS webhook TRANSMITTING → TRANSMITTED → ACKNOWLEDGED
                            ─10▶ acknowledge received invoices   ─11▶ VAT post-payment report
Anyone ─▶ scan QR (MBS360) ─▶ NRS verify_stamp ─▶ issuer + IRN

Steps 1–6 happen synchronously in one API call plus the QR call. Steps 7–11 are performed by the platform after signing (see Lifecycle after signing).

Prerequisites

Before the first invoice can be signed, the following NRS artefacts are configured once per platform organisation (via PUT /api/v1/nigeria/settings) and once per taxpayer business (via POST /api/v1/nigeria/businesses and PUT /api/v1/nigeria/businesses/{business_id}/keys):

Artefact	Source	Used for
x-api-key + x-api-secret	NRS service-provider portal → Generate API key	Authenticating every NRSMBS call
Base URL	Sandbox (fixed) or production (portal → Switch to production)	Environment
business_id, Service ID, TIN	Returned by NRS when the taxpayer business is onboarded (entity + business)	business_id in every invoice; Service ID inside the IRN
Cryptographic bundle — public_key + certificate (crypto_keys.txt)	NRS portal → Manage Cryptographic Keys — per business	Generating the QR code; decrypting downloaded invoices
Webhook URL and egress IPs	Registered in the NRS portal (Developers → Add Webhook URL, IP Access List)	Receiving transmission notifications; allow-listing outbound calls

The QR must belong to the supplier

The certificate embedded in the QR identifies the issuer that NRS returns on verification. Always store each business's own crypto_keys.txt with PUT /businesses/{business_id}/keys and pass that business_id when generating the QR — never the sample bundle printed in the NRS documentation (its issuer is "Test Business") and never another business's bundle.

Authentication

Every request carries your platform API key:

X-API-Key: pk_live_your_api_key_here
Content-Type: application/json

API keys are organisation-scoped; the organisation's NRS credentials, businesses and keys are resolved from the key. NRS credentials are never sent by integrators on a per-call basis.

Endpoints

Method	Path	Purpose
GET	/api/v1/nigeria/settings	Show the organisation's NRS configuration (masked) and the identity NRS resolved for it
PUT	/api/v1/nigeria/settings	Set NRS api_key, api_secret, base_url, default service_id / business_id, org-level QR keys
GET	/api/v1/nigeria/businesses	List onboarded taxpayer businesses (with has_keys)
POST	/api/v1/nigeria/businesses	Onboard a taxpayer business with NRS (creates entity + business, returns business_id and Service ID)
PUT	/api/v1/nigeria/businesses/{business_id}/keys	Store that business's NRS cryptographic bundle (public key + certificate)
POST	/api/v1/nigeria/validate	Validate an invoice with NRSMBS; with "sign": true also sign it → IRN registered
POST	/api/v1/nigeria/qr	Generate the QR code for an IRN using the business's bundle; optionally verified with NRS verify_stamp
POST	/api/v1/nigeria/decrypt	Download the signed invoice from NRSMBS and decrypt it (AES-256-CFB)

Settings — NRS credentials and environment

PUT /api/v1/nigeria/settings

{
  "api_key": "<x-api-key UUID from the NRS portal>",
  "api_secret": "••••••••••••••••••••••••••••••••",
  "base_url": "https://eivc-k6z6d.ondigitalocean.app",
  "service_id": "39EADBB3",
  "business_id": "3617777c-dbb3-436d-8af8-1a3aca6730d2"
}

GET /api/v1/nigeria/settings → the platform masks secrets and reports the identity NRS resolved for the credentials:

{
  "configured": true,
  "api_key_masked": "55ca...9ba4",
  "has_api_secret": true,
  "base_url": "https://eivc-k6z6d.ondigitalocean.app",
  "service_id": "39EADBB3",
  "business_id": "3617777c-dbb3-436d-8af8-1a3aca6730d2",
  "has_public_key": true,
  "has_certificate": true,
  "business_name": "Example Supplier Ltd",
  "tin": "12345678-0001",
  "entity_id": "e7c765cc-39ea-4044-8caa-6fb6823d10fb",
  "discovered": true
}

List businesses

GET /api/v1/nigeria/businesses

{
  "ok": true,
  "businesses": [
    {
      "business_id": "3617777c-dbb3-436d-8af8-1a3aca6730d2",
      "business_name": "Example Supplier Ltd",
      "tin": "12345678-0001",
      "service_id": "39EADBB3",
      "entity_id": "e7c765cc-39ea-4044-8caa-6fb6823d10fb",
      "has_keys": true
    }
  ],
  "default_business_id": "3617777c-dbb3-436d-8af8-1a3aca6730d2"
}

Onboard a business

POST /api/v1/nigeria/businesses — registers a taxpayer (entity + business) with NRSMBS under your service-provider account and returns the identifiers you need for invoicing.

{
  "name": "Lagos Retail Holdings Plc",
  "tin": "23456789-0001",
  "reference": "LRH-001"
}

Response — same shape as List businesses, now including the new business with its NRS business_id and service_id. Store the business's cryptographic bundle next.

Store a business's cryptographic bundle

PUT /api/v1/nigeria/businesses/{business_id}/keys — the two values from that business's crypto_keys.txt (downloaded from the NRS portal → Manage Cryptographic Keys), passed verbatim:

{
  "nrs_public_key": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K…",
  "certificate_b64": "VVhrallFNVZUdDV0eUJmYWV1RmYwUXJRNEhTdXlhcU1pOGZsWF35sfhWRT0="
}

Key material is stored encrypted and is never echoed back — GET /businesses only reports has_keys: true.

Validate and sign an invoice

POST /api/v1/nigeria/validate

Field	Type	Description
invoice	object	The NRS invoice JSON (schema below). business_id, invoice_kind and irn are auto-filled when absent
sign	boolean	false (default) — validate only; true — validate, then sign (registers the IRN with NRS)
invoice_no	string	Your invoice number, used to build the IRN <invoice_no>-<Service ID>-<YYYYMMDD> when invoice.irn is not supplied
business_id	string	Which onboarded business issues the invoice (defaults to the organisation's primary business)

Example — the payload below was validated (200) and signed (201) on the NRS sandbox:

{
  "sign": true,
  "invoice_no": "INV0706",
  "business_id": "3617777c-dbb3-436d-8af8-1a3aca6730d2",
  "invoice": {
    "business_id": "3617777c-dbb3-436d-8af8-1a3aca6730d2",
    "irn": "INV0706-39EADBB3-20260706",
    "issue_date": "2026-07-06",
    "due_date": "2026-08-05",
    "invoice_type_code": "380",
    "invoice_kind": "B2B",
    "document_currency_code": "NGN",
    "tax_currency_code": "NGN",
    "tax_point_date": "2026-07-06",
    "buyer_reference": "PO-2026-0456",
    "accounting_supplier_party": {
      "party_name": "Example Supplier Ltd",
      "tin": "12345678-0001",
      "email": "billing@example-supplier.ng",
      "telephone": "+2348025409900",
      "business_description": "Cloud software and implementation services",
      "postal_address": {
        "street_name": "Plot 14, Adetokunbo Ademola Street",
        "city_name": "Victoria Island",
        "postal_zone": "101241",
        "country": "NG"
      }
    },
    "accounting_customer_party": {
      "party_name": "Lagos Retail Holdings Plc",
      "tin": "23456789-0001",
      "email": "ap@lagosretail.example.ng",
      "telephone": "+2348020000000",
      "business_description": "Retail holdings",
      "postal_address": {
        "street_name": "22 Marina Road",
        "city_name": "Lagos Island",
        "postal_zone": "101001",
        "country": "NG"
      }
    },
    "actual_delivery_date": "2026-07-06",
    "payment_means": [
      { "payment_means_code": "30", "payment_due_date": "2026-08-05" }
    ],
    "payment_terms_note": "Net 30 days",
    "tax_total": [
      {
        "tax_amount": 37500,
        "tax_subtotal": [
          {
            "taxable_amount": 500000,
            "tax_amount": 37500,
            "tax_category": { "id": "STANDARD_VAT", "percent": 7.5 }
          }
        ]
      }
    ],
    "legal_monetary_total": {
      "line_extension_amount": 500000,
      "tax_exclusive_amount": 500000,
      "tax_inclusive_amount": 537500,
      "payable_amount": 537500
    },
    "invoice_line": [
      {
        "hsn_code": "8523.49",
        "product_category": "Cloud subscription - standard tier",
        "invoiced_quantity": 10,
        "line_extension_amount": 300000,
        "item": {
          "name": "Cloud Subscription - Standard Tier",
          "description": "Annual cloud subscription, standard tier",
          "sellers_item_identification": "HP-CLD-STD"
        },
        "price": { "price_amount": 30000, "base_quantity": 1, "price_unit": "EA" }
      },
      {
        "isic_code": "6202",
        "service_category": "Computer consultancy and facilities management",
        "invoiced_quantity": 40,
        "line_extension_amount": 200000,
        "item": {
          "name": "Implementation Consulting",
          "description": "Implementation consulting services",
          "sellers_item_identification": "HP-PS-IMPL"
        },
        "price": { "price_amount": 5000, "base_quantity": 1, "price_unit": "HUR" }
      }
    ]
  }
}

Response — validated and signed:

{
  "ok": true,
  "validation": { "code": 200, "data": { "ok": true } },
  "sign": { "code": 201, "data": { "ok": true } },
  "signed": true,
  "duplicate": false,
  "issues": [],
  "message": null,
  "transaction_id": "9d3d1c9a-5b2f-4a48-9c8f-2b0d1b6c7e21"
}

Response — NRS rejected the invoice (nothing is signed; fix the listed fields and resubmit):

{
  "ok": false,
  "validation": {
    "code": 400,
    "error": {
      "id": "0b1c2d3e-…",
      "handler": "invoice_actions",
      "details": "invoicerequest.invoice.invoiceline[0].hsn_code is required when product_category is provided",
      "public_message": "Invoice validation failed"
    }
  },
  "sign": null,
  "signed": false,
  "issues": ["Line 1: HSN code is required when product category is provided."],
  "message": "Line 1: HSN code is required when product category is provided."
}

Response — the IRN was already signed today (sign is idempotent on IRN; the platform reports it rather than retrying):

{
  "ok": false,
  "signed": false,
  "duplicate": true,
  "issues": [],
  "message": "Invoice INV0706 was already signed and submitted to NRS today. Use a new invoice number to sign again."
}

B2C example

The same schema with "invoice_kind": "B2C". Note that the NRS sandbox still requires a non-empty accounting_customer_party.tin for B2C invoices; use the customer's TIN where available.

{
  "sign": true,
  "invoice_no": "B2C0706A",
  "invoice": {
    "invoice_kind": "B2C",
    "issue_date": "2026-07-07",
    "invoice_type_code": "380",
    "document_currency_code": "NGN",
    "tax_currency_code": "NGN",
    "accounting_supplier_party": { "party_name": "Example Supplier Ltd", "tin": "12345678-0001", "email": "billing@example-supplier.ng" },
    "accounting_customer_party": { "party_name": "Walk-in customer", "tin": "00000000-0001", "email": "customer@example.ng" },
    "tax_total": [ { "tax_amount": 1500, "tax_subtotal": [ { "taxable_amount": 20000, "tax_amount": 1500, "tax_category": { "id": "STANDARD_VAT", "percent": 7.5 } } ] } ],
    "legal_monetary_total": { "line_extension_amount": 20000, "tax_exclusive_amount": 20000, "tax_inclusive_amount": 21500, "payable_amount": 21500 },
    "invoice_line": [ { "hsn_code": "8471.30", "invoiced_quantity": 1, "line_extension_amount": 20000, "item": { "name": "Tablet accessory" }, "price": { "price_amount": 20000, "base_quantity": 1, "price_unit": "EA" } } ]
  }
}

Generate the QR code

POST /api/v1/nigeria/qr — builds the QR for an IRN using the business's cryptographic bundle and (when NRS credentials are configured) verifies it with NRS verify_stamp before returning.

{
  "invoice_no": "INV0706",
  "business_id": "3617777c-dbb3-436d-8af8-1a3aca6730d2"
}

{
  "ok": true,
  "irn": "INV0706-39EADBB3-20260706",
  "signature_b64": "aLI+LP+gVeA4dTMTYAdemTMOnIY67d0AB1pmH2QXXN2kzoXxLo+QPTNaOlxHsKyKA/8Kv…",
  "png_base64": "iVBORw0KGgoAAAANSUhEUgAA…",
  "issued_at_unix": 1783338163,
  "verified": true,
  "verify_message": "NRS validated this QR back to the IRN."
}

signature_b64 is the exact QR content; png_base64 is a ready-to-embed PNG. If the business has no bundle stored the response is { "ok": false, "needs_keys": true, "message": "QR signing needs this business's NRS cryptographic bundle …" }.

How the QR is built (per the NRS IRN Signing specification):

1. payload = { "irn": "<IRN>.<unix timestamp>", "certificate": "<certificate value from crypto_keys.txt, verbatim>" }
2. ciphertext = RSA-PKCS#1 v1.5 encrypt(payload, NRS public key from crypto_keys.txt)
3. QR content = Base64(ciphertext) — rendered as a QR image on the invoice.

NRS (or the MBS360 app) decrypts the QR and returns the issuer and the IRN; because the certificate is the supplier business's own, the issuer is the supplier named on the invoice.

Download and decrypt a signed invoice

POST /api/v1/nigeria/decrypt

{ "irn": "INV0706-39EADBB3-20260706" }

{
  "ok": true,
  "irn": "INV0706-39EADBB3-20260706",
  "iv_hex": "7a31…",
  "pub": "g5nSzZwj4bdvw668292ypyNTA",
  "invoice": { "business_id": "3617777c-…", "irn": "INV0706-39EADBB3-20260706", "…": "…" },
  "not_found": false
}

The platform calls GET base_url/api/v1/invoice/download/{IRN}, which returns { iv_hex, pub, data }, and decrypts data with AES-256-CFB where the key is pub + the first hyphen segment of the NRS api key and the IV is iv_hex. not_found: true means NRS has no signed invoice for that IRN yet.

Lifecycle after signing (transmission, acknowledgement, VAT reporting)

Once an invoice is signed, the platform — acting as Access Point Provider — completes the NRSMBS lifecycle on the taxpayer's behalf. Integrators do not call these steps directly; progress is visible on the portal Transactions page and through notifications.

Step	NRSMBS endpoint	What the platform does
Confirm	GET base_url/api/v1/invoice/confirm/{IRN}	Reads payment_status, transmitted, delivered for the IRN
Download	GET base_url/api/v1/invoice/download/{IRN}	Retrieves and decrypts the signed invoice (see above)
Update	PATCH base_url/api/v1/invoice/update/{IRN}	Payment status PENDING / PARTIAL (with amount) / PAID / REJECTED
Transmit	POST base_url/api/v1/invoice/transmit/{IRN}	Delivers the e-invoice to the counterparties; GET …/transmit/self-health-check verifies the APP setup first
Webhook	NRS → POST https://<platform-host>/nrs/webhook	{ "irn": "…", "message": "TRANSMITTING" | "TRANSMITTED" | "ACKNOWLEDGED" | "FAILED" } — processed idempotently, answered 200 OK
Receive / acknowledge	PATCH base_url/api/v1/invoice/transmit/{IRN} · GET …/transmit/pull · GET …/transmit/lookup/{IRN} · GET …/transmit/lookup/tin/{TIN}	Confirms receipt of invoices addressed to the platform's businesses; pulls and looks up invoices
VAT report	POST base_url/api/v1/vat/postpayment	{ agent_tin, beneficiary_tin, irn, base_amount, vat_rate, vat_calculated, total_amount, currency, transaction_date, integrator_service_id, vat_status }
QR verification	POST https://api.firsmbs.com/api/v1/integration/verify_stamp	Used by the platform (and by MBS360) to verify a QR → issuer + IRN

Webhook contract

NRS dispatches webhooks from its Convoy dispatcher (User-Agent: Convoy/…). On registration NRS sends a test notification, so the endpoint must be reachable and answer 200 OK immediately; failures are retried and eventually suppressed. Events are stateless — the platform records (irn, message) idempotently and derives the transmission status.

Mapping to NRSMBS

Platform endpoint	NRSMBS endpoint(s)	Auth to NRS
POST /api/v1/nigeria/validate	POST base_url/api/v1/invoice/validate (and …/invoice/sign when sign: true)	x-api-key + x-api-secret
POST /api/v1/nigeria/qr	local RSA encryption + POST api.firsmbs.com/api/v1/integration/verify_stamp	x-api-key + x-api-secret
POST /api/v1/nigeria/decrypt	GET base_url/api/v1/invoice/download/{IRN} + local AES-256-CFB decrypt	x-api-key + x-api-secret
POST /api/v1/nigeria/businesses	NRS entity + business creation for the service-provider account	x-api-key + x-api-secret
GET /api/v1/nigeria/settings (discovery)	NRS account/business lookup for the configured credentials	x-api-key + x-api-secret

Invoice schema essentials

Field	Required	Notes
business_id	✅	NRS business UUID — auto-filled from the selected business
irn	✅	<invoice number>-<Service ID>-<YYYYMMDD> — auto-built from invoice_no + issue date when omitted
issue_date, due_date	✅ / optional	ISO dates; the IRN suffix must match the issue date
invoice_type_code	✅	380 invoice, 381 credit note, 383 debit note … (UNCL1001)
invoice_kind	✅	B2B, B2C, B2G — defaults to B2B when omitted
document_currency_code, tax_currency_code	✅	NGN
accounting_supplier_party	✅	party_name, tin, email (+ telephone, business_description, postal_address)
accounting_customer_party	✅	Same shape; the sandbox requires a non-empty tin even for B2C
tax_total[]	✅	tax_amount + tax_subtotal[] with taxable_amount, tax_amount, tax_category { id, percent }
legal_monetary_total	✅	line_extension_amount, tax_exclusive_amount, tax_inclusive_amount, payable_amount
invoice_line[]	✅	each line: hsn_code or isic_code, invoiced_quantity, line_extension_amount, item { name, … }, price { price_amount, base_quantity, price_unit }
payment_means[], payment_terms_note, buyer_reference, tax_point_date, actual_delivery_date	optional	Recommended

The authoritative schema, code lists (tax categories, unit codes, HSN/ISIC) and changelog are published by NRS at einvoice.nrs.gov.ng/docs; the platform validates against them before calling NRSMBS and returns NRS's own field-level messages in issues[].

Errors and idempotency

Situation	Response
Missing NRS credentials or business for the organisation	400 with a message pointing to Settings → NRS / Businesses
NRS validation failure (schema / business rules)	200 body with ok: false, validation.code = 400, human-readable issues[]; nothing is signed
Duplicate IRN on sign	ok: false, duplicate: true — use a new invoice number (the IRN includes the date, so the same number is reusable tomorrow)
NRS unavailable / 5xx	ok: false with message; the platform retries transient failures with back-off and logs every attempt with a correlation ID
QR without stored keys	ok: false, needs_keys: true
Decrypt before sign	ok: false, not_found: true

Sandbox testing checklist

1. PUT /settings with the sandbox api_key / api_secret (base URL defaults to the sandbox); GET /settings should show discovered: true with your business name and TIN.
2. POST /businesses for a test taxpayer, then PUT /businesses/{id}/keys with that business's crypto_keys.txt.
3. POST /validate with sign: false until ok: true; then sign: true → signed: true.
4. POST /qr → verified: true; scan the PNG with the MBS360 app or paste signature_b64 into the NRS Validate QR Code self-test — the issuer must be your business.
5. POST /decrypt → the invoice you signed.
6. Register the webhook URL and the platform's egress IPs in the NRS portal (Developers, IP Access List) before switching to production.

Sandbox gotchas

• invoice_kind is mandatory — the platform defaults it to B2B, but set it explicitly for B2C/B2G.
• B2C still needs a customer TIN on the sandbox — an empty accounting_customer_party.tin returns HTTP 400.
• Use the certificate value verbatim in the QR payload — decoding it first makes NRS answer "Unknown Issuer".
• One IRN per invoice number per day — the date is part of the IRN.
• HSN or ISIC per line — goods lines carry hsn_code, service lines isic_code.
• The NRS Invoice Decryption self-test page uses a different (Laravel-style AES-256-CBC) envelope than the API download route; the API route is the one the platform implements.

Related

• Validation · Error handling · API reference
• NRS: API documentation · Become a service provider