ediverse

Type to search across standards, messages, tools and glossary.

ediverse Explore the platform

Spotlight PEPPOL BIS Billing 3.0 The EU e-invoicing mandate is here — France Sept 2026, Belgium Jan 2026, Germany 2025.

— 01

Foundations

— 02

Standards

— 03

Flagship messages

— 04

Tools

Nigeria — FIRS, MBS and UBL e-invoicing

Nigeria deployed in 2022 a B2B e-invoicing pilot under the FIRS (Federal Inland Revenue Service). The Merchant-Buyer System (MBS), based on UBL 2.1 with FIRS extensions, entered mandatory phase on 1 February 2025 for large taxpayers with progressive extension through 2027.

Regulatory timeline

  • 16 April 2007 — FIRS Establishment Act. Autonomous legal status of FIRS, independent of the Ministry of Finance, in charge of federal tax collection.
  • 2 January 2020 — Finance Act 2019. Major modernisation: introduces VAT at 7.5 %, lays the foundations for increased tax digitalisation.
  • 1 July 2022 — eInvoice pilot launch. FIRS launches the MBS (Merchant-Buyer System) programme for cross-border transactions, UBL-aligned XML schema.
  • 11 January 2024 — Finance Act 2023. Gives FIRS the legal authority to make B2B e-invoicing mandatory and set technical modalities.
  • 1 October 2024 — Mandatory pilot for large taxpayers. FIRS selection of 100 large enterprises in mandatory pilot, UBL sandbox with validation round-trip.
  • 1 February 2025 — Mandatory phase 1. All taxpayers with turnover > NGN 5 billion must issue via MBS for B2B transactions. IRN mandatory on physical printed invoices.
  • 1 July 2025 — Mandatory phase 2. Extension to taxpayers with turnover > NGN 1 billion.
  • 2026-2027 — Phase 3 generalisation. Progressive extension to mid-market and ultimately to all VAT-registered enterprises.

Technical schema

The FIRS format is a standard UBL 2.1 with customization urn:firs.gov.ng:einvoice:1.0 and proprietary extensions:

  • TIN: format NNNNNNNN-NNNN, 8 identifier digits + 4 branch code digits (head office 0001).
  • InvoiceTypeCode: 380 (Commercial invoice), 381 (Credit note), 383 (Debit note), 386 (Prepayment invoice).
  • DocumentCurrencyCode: NGN, USD, EUR…; the CBN (Central Bank of Nigeria) exchange rate must accompany invoices in foreign currencies.
  • TaxScheme.ID: VAT (Value Added Tax, 7.5 %), WHT (Withholding Tax, variable by service / good nature).
  • firs:FIRSIRN: Invoice Reference Number assigned by FIRS after validation, format FIRS-YYYY-IRN-NNNNNNNN.
  • firs:QRCode: QR Code embedded in the document, base64, encodes {TIN_seller, TIN_buyer, total, VAT, IRN, hash}.

Minimal example of a FIRS UBL invoice:

xmlfirs-einvoice-ubl.xml
<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
         xmlns:firs="urn:firs:ng:einvoice:extension:1.0">
  <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
  <cbc:CustomizationID>urn:firs.gov.ng:einvoice:1.0</cbc:CustomizationID>
  <cbc:ID>NG-2026-00000142</cbc:ID>
  <cbc:IssueDate>2026-05-16</cbc:IssueDate>
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>NGN</cbc:DocumentCurrencyCode>
  <cac:AccountingSupplierParty>
    <cac:Party>
      <cac:PartyIdentification>
        <cbc:ID schemeID="TIN">12345678-0001</cbc:ID>
      </cac:PartyIdentification>
      <cac:PartyName>
        <cbc:Name>Ediverse Demo Nigeria Ltd</cbc:Name>
      </cac:PartyName>
      <cac:PostalAddress>
        <cbc:StreetName>Broad Street 25</cbc:StreetName>
        <cbc:CityName>Lagos</cbc:CityName>
        <cac:Country><cbc:IdentificationCode>NG</cbc:IdentificationCode></cac:Country>
      </cac:PostalAddress>
    </cac:Party>
  </cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty>
    <cac:Party>
      <cac:PartyIdentification>
        <cbc:ID schemeID="TIN">87654321-0001</cbc:ID>
      </cac:PartyIdentification>
    </cac:Party>
  </cac:AccountingCustomerParty>
  <cac:TaxTotal>
    <cbc:TaxAmount currencyID="NGN">3750.00</cbc:TaxAmount>
  </cac:TaxTotal>
  <cac:LegalMonetaryTotal>
    <cbc:PayableAmount currencyID="NGN">53750.00</cbc:PayableAmount>
  </cac:LegalMonetaryTotal>
  <cac:InvoiceLine>
    <cbc:ID>1</cbc:ID>
    <cbc:InvoicedQuantity unitCode="EA">1</cbc:InvoicedQuantity>
    <cbc:LineExtensionAmount currencyID="NGN">50000.00</cbc:LineExtensionAmount>
    <cac:Item><cbc:Name>Cloud services May 2026</cbc:Name></cac:Item>
  </cac:InvoiceLine>
  <firs:FIRSIRN>FIRS-2026-IRN-00000142</firs:FIRSIRN>
  <firs:QRCode>...</firs:QRCode>
</Invoice>

Submission flow

The seller authenticates with FIRS (OAuth 2.0 client credentials + signed JWT) then submits their UBL invoice via POST /v1/invoices on einvoice.firs.gov.ng. FIRS validates in real time (TIN, schema, calculations, duplicates) then assigns an IRN and a QR Code, and returns the signed document.

textfirs-mbs-flow.txt
┌──────────────┐    ┌────────────────────┐    ┌──────────────┐
│ NG supplier  │───>│ FIRS MBS           │───>│ NG customer  │
│ (ERP, UBL)   │    │ Merchant-Buyer     │    │ (receipt +   │
│ + TIN + auth │    │ System einvoice    │    │  IRN/QR      │
│              │    │ .firs.gov.ng       │    │  lookup)     │
└──────────────┘    └─────────┬──────────┘    └──────────────┘
                              │
                              ▼
                  ┌────────────────────┐
                  │ FIRS assigns IRN   │ ← real-time
                  │ + QR Code + Hash   │   validation
                  │ + FIRS signature   │   or rejection
                  └────────────────────┘

The buyer receives the validated invoice through usual channels (email, EDI, seller portal). They can verify the IRN on einvoice.firs.gov.ng or scan the embedded QR Code. WHT (Withholding Tax) controls are automated via the IRN: FIRS reconciles flows to pre-fill returns.

Validation

  • FIRS: firs.gov.ng — official site, publications, tax laws, eInvoice FAQ.
  • FIRS eInvoice (production): einvoice.firs.gov.ng — MBS submission portal, IRN lookup, taxpayer access.
  • FIRS eInvoice (UAT sandbox): uat.einvoice.firs.gov.ng — test environment, REST API, swagger doc, integration tests.
  • Joint Tax Board (JTB): jtb.gov.ng — coordination between FIRS (federal taxes) and SIRS (state taxes), TIN verification.

Common pitfalls

  1. Strict TIN format with branch code. The Nigerian TIN is not just 8 digits: it's NNNNNNNN-NNNN with mandatory branch suffix. Head office uses -0001, subsidiaries -0002, -0003… Common error: sending a TIN without suffix → systematic API rejection.
  2. WHT (Withholding Tax) — complex component. Beyond the 7.5 % VAT, many B2B transactions are subject to a Withholding Tax (5 % services, 10 % interest, 5 % rent…). The FIRS UBL must carry these taxes in cac:TaxTotal with TaxScheme.ID = WHT. Omitting = penalties on the buyer side.
  3. Volatile NGN + multi-currency. The Naira experienced strong devaluations in 2023-2024. USD/EUR invoices must always reference the CBN exchange rate of the day: not the parallel market rate. Test the daily CBN rate update in the pipeline.
  4. UAT sandbox vs Prod — schema drift. FIRS iterates quickly on the schema; UAT and Prod can diverge temporarily (sometimes 2-3 weeks). Always validate against the most recent XSDs and test on UAT 7-10 days before each Prod release.
  5. IRN to print on physical invoices. For taxpayers transitioning to full e-invoicing, FIRS requires that printed invoices (still tolerated in transition) carry the IRN and QR Code. A printed invoice without IRN is not fiscally enforceable.