FIRS E-Invoicing Nigeria: Merchant-Buyer Solution Explained

Nigeria's Merchant-Buyer Solution is a central clearance platform, not a Peppol network. A supplier in scope builds a structured invoice, sends it to the tax authority's platform over HTTPS for validation and signing, and gets back a cleared invoice reference number and a QR signature before the document reaches the buyer. This article sets out what the platform does, what it returns, and what breaks — taken from the authority's own developer documentation and from our own integration testing against its sandbox.

Why does this page say "FIRS" when the documentation says "NRS"?

Because both names are in use for the same thing. The e-invoicing documentation is published by the Nigeria Revenue Service at einvoice.nrs.gov.ng, the platform's exchange host is still api.firsmbs.com, and "FIRS" remains what most people search for.

Where this page says FIRS, it means the same authority and the same platform. Nothing about the integration changes with the name: the endpoints, the schema, the certification tests and the service-provider roles are all published under the new name and behave as the older material describes. If you have internal documents that refer to the Federal Inland Revenue Service, they are not out of date on the technical substance — but the developer documentation you should be reading day to day now lives under the newer domain.

What is the FIRS Merchant-Buyer Solution?

The Merchant-Buyer Solution is Nigeria's national e-invoicing platform. Invoices are submitted to it for validation and signing before they are exchanged, and it returns a cleared invoice reference number and a QR signature. Providers connect over HTTPS REST with an API key and secret.

Everything about the platform follows from that one sentence. It is a continuous transaction control regime: the tax authority sits in the path of the invoice rather than reading a report afterwards. In practice that means three things for anyone planning a rollout.

• The platform is authoritative, not advisory. An invoice that has not passed validation and signing has no cleared identity. There is no "send now, fix later" path.
• Your software talks to one central place, over ordinary HTTPS with two headers — an API key and an API secret, issued per registered application from the service-provider dashboard. There is no certificate-based transport layer to stand up, and no directory to look the buyer up in.
• The platform publishes the code lists it validates against, as ordinary read endpoints: units of measure, currencies, countries, tax categories, payment means, service codes, Nigerian states, local government areas and invoice type codes. Pull them; do not hard-code them.

The surface is grouped roughly as taxpayer authentication, entity and business onboarding, the invoice lifecycle, the resource code lists, transmission between parties, and VAT reporting. All of it is documented at einvoice.nrs.gov.ng/docs.

Is Nigeria's e-invoicing system built on Peppol?

No. Nigeria runs a central clearance model, not a Peppol four-corner exchange. There is no AS4 transport, no SMP lookup and no Peppol participant identifier anywhere in the flow. The platform's "Access Point Provider" role is a Nigerian role defined by the tax authority, and it is not a Peppol Access Point.

This is the single most expensive misunderstanding in Nigerian e-invoicing projects, and the name collision is what causes it. Side by side:

If you want the four-corner model itself explained, we cover it in Peppol vs PINT. The closest comparable to Nigeria among the systems we work in daily is not a Peppol country at all — it is Saudi Arabia, whose clearance regime is described in our ZATCA e-invoicing guide.

Two practical consequences follow. First, if you are shopping for "a Peppol access point for Nigeria", that is not the product you need; you need your own registration on the Nigerian platform, or a provider registered on it. Second, an architecture document, an RFP response or a compliance statement that describes Nigeria in Peppol terms — corners, AS4, SMP lookup, participant identifiers — is describing a different country's system, and a reviewer who knows the platform will say so.

Who has to use it, and from when?

The platform handles business-to-business, business-to-government and business-to-consumer invoices: the payload carries an invoice_kind field with exactly those three values. Which taxpayers must use it, and from which date, is set by the authority's own rollout notices, and this page does not restate a date it cannot cite to the authority.

That refusal is deliberate. Nigeria's rollout schedule has been restated and revised in secondary coverage more than once, and a cohort date repeated from a summary is the commonest way a readiness plan ends up planning for the wrong quarter. Check your own position against the notices the authority publishes and against any message addressed to your own TIN in the portal.

What the platform's own documentation does establish is worth having, because it tells you what the system is built to handle:

• All three invoice kinds are live in the schema. invoice_kind accepts B2B, B2G and B2C, and the field entered the schema in the documented changes of December 2025.
• Consumer receipts carry a QR code. The QR requirement is specific to the business-to-consumer case, and the authority publishes a self-test page for it.
• A taxpayer can report directly. Reporting does not have to run through an integrator: the documented changes of November 2025 allow a taxpayer to report with its own keys, using a reserved value in the integrator field.
• Foreign customers are handled, with a condition. A foreign tax identifier is acceptable for a customer that is not supplying or earning in Nigeria.
• Cross-border invoicing is not finished. The documented changes of April 2026 describe a cross-border schema as being prepared, with no timeline announced. If your Nigerian entity issues export invoices, that is the open item to track.

For the rollout picture as we track it, see our companion article on the Nigeria e-invoicing mandate 2026, and our Nigeria e-invoicing page for what we operate locally. The wider country-by-country view is in the e-invoicing mandates 2026 tracker.

How is an invoice cleared, and what comes back?

Validate first, then sign. A validated invoice returns HTTP 200 with ok: true; signing returns 201. From that point the invoice exists under its reference number and can be confirmed, downloaded in encrypted form, transmitted to the other party, and updated as it is paid.

The lifecycle, in the order you will implement it:

Notifications are the part teams forget

Transmission is asynchronous, and the platform tells you what happened through a webhook rather than in the response body. You register a URL in the service-provider portal; on registration the platform immediately dispatches a test notification to check the endpoint is reachable. Your endpoint must accept POST and answer 200, or delivery is retried and eventually suppressed.

The payload is small — an invoice reference number and a message — and the message is one of TRANSMITTING, TRANSMITTED, ACKNOWLEDGED or FAILED. Notifications are stateless and event-driven, so process them idempotently: the same message can arrive twice, and the order is not guaranteed. An invoice counts as completely transmitted only once every party has acknowledged it, which is why the acknowledgement call belongs in your build from the start rather than in a later phase.

Payment status is part of the record, not your ledger's private business

The payment lifecycle is modelled on the platform: PENDING, PARTIAL, PAID and REJECTED. A partial payment carries the amount of that instalment and can be sent repeatedly against one invoice; when the invoice is settled you move it to PAID and drop the amount. Separately, the VAT post-payment call records the tax side of the transaction — the supplier and beneficiary TINs, the base amount, other taxes, the VAT calculated and the rate, which in the authority's own example payload is 7.5.

What format and identifiers does Nigeria use?

A UBL-derived invoice, submitted as JSON, up to two megabytes. Eleven fields are mandatory, including the invoice reference number, the invoice kind, and both the document and tax currencies. Parties are identified by TIN — or by an RC- prefixed incorporation number where a business buyer has none.

The mandatory set

The documented invoice schema runs to 35 fields, of which the mandatory ones are the business identifier, the invoice reference number, the issue date, the invoice type code, the invoice kind, the document currency code, the tax currency code, the supplier party, the tax total, the legal monetary total and the invoice lines. The supplier party itself must carry a TIN and an email address.

Below that, every invoice line needs a classification code: an HSN code where the line is goods, an ISIC code where it is services. This is the field most likely to fail a document that otherwise looks complete, because a generator that emits it for the first line and not the second produces an invoice that reads correctly and validates as an error.

Identifiers and geography

• TIN is the primary party identifier. Where a business-to-business buyer genuinely has no TIN, the documented changes of October 2025 allow the incorporation number in the same field, prefixed RC-.
• State and local government area are required on the accounting parties. The platform serves both lists — Nigerian states in the NG- form, and the full local-government list — as resource endpoints.
• The invoice reference number is composed by you, not issued by an endpoint. It is the invoice number, the service identifier assigned to your business, and the date, joined with hyphens: {InvoiceID}-{ServiceID}-{YYYYMMDD}. The service identifier arrives when the business is registered on the platform.

The code lists, and why you should fetch them

The platform serves its own reference data: unit-of-measure codes on the UN/ECE Recommendation 20 and 21 lists, ISO 4217 currencies, ISO 3166 countries, payment means on the UN/CEFACT 4461 list, invoice type codes on UN/CEFACT 1001, service codes, states and local government areas, and the tax categories — which as of the documented changes of February 2026 include withholding tax, stamp duty and exempted alongside the standard and zero-rated cases.

Two of these have moved recently. Tax categories gained those three values in February 2026, and the documented changes of April 2026 made the price unit code and the base quantity mandatory on pricing, with the unit code taken from the platform's own quantity-code list. A build that hard-codes reference data will pass today and fail on the next revision; a build that caches the resource endpoints will not.

How is the QR code produced, and what does it prove?

You produce it yourself; the platform does not hand you an image. Compose the invoice reference number with a Unix timestamp and your certificate, encrypt that payload with the authority's RSA public key, and base64-encode the ciphertext. That string is the QR content, and scanning it resolves back to the invoice reference and the issuing business.

The keys come from the service-provider dashboard, under the cryptographic-keys page, as a small JSON file holding a public key and a certificate. The encryption is RSA with PKCS#1 v1.5 padding. The payload is the invoice reference number with the timestamp appended after a dot, plus the certificate. Any QR library renders the resulting string.

One trap is worth the paragraph. The documentation prints a sample key bundle, and a QR built with it validates perfectly — but it resolves to the documentation's own demo business rather than to you. We hit exactly this: the QR verified, and the issuer it reported was the sample identity while the invoice named the real supplier. In production the rule is simple and absolute: a taxpayer's QR is built with that taxpayer's own certificate, never with a provider's certificate and never with the sample. If your dashboard hands back the same certificate value that appears in the public documentation, the account has no key of its own yet, and that is a question for the authority's support desk before you go any further.

What happens when validation fails?

Nothing goes forward. Signing is refused until validation passes, so a rejected invoice is not a cleared invoice with a warning attached — it does not exist yet. The platform answers HTTP 400 with a request identifier, the handler that rejected it, a machine-readable detail and a user-facing message.

That error envelope is genuinely useful, and it is worth persisting all four parts. The request identifier is what the authority's support desk will ask for. The machine-readable detail names the field; the user-facing message is the one you can show an accounts-payable clerk without translating it first.

Three failure patterns account for most of the time lost:

1. A missing per-line classification code. One line without its HSN or ISIC code fails the whole document. Our own first validation run failed for exactly this reason, on the second line of a two-line invoice.
2. Building to the sandbox rather than to the documentation. When we tested, the documentation listed the invoice kind as mandatory while the sandbox accepted a payload without it and signed it. Build to the documented schema: the sandbox being permissive today is not a promise about production tomorrow.
3. Discovering a schema change late. The platform's changelog is the authority's own record of what has moved, and its stated policy is a three-month grace window before a breaking change is enforced. That window is only useful to a team that is reading the changelog.

There is a fourth, quieter one: burning your quota on documents your own system could have rejected. Validate locally first — structure, totals, the classification code on every line, the state and local-government values — and send the platform only what you believe is correct.

How do you register as a service provider?

Through the portal, in one of two roles. A System Integrator embeds compliant invoicing into taxpayer systems; an Access Point Provider operates the conduit that submits, validates and transmits. You complete a business profile, accept the service level agreement, submit the registration form, then build and self-test.

The authority defines the two roles in its own words. A System Integrator "ensures secure integration between taxpayer accounting systems and the NRS e-invoicing platform" and configures those systems "to generate compliant invoices and oversee their digital signing and transmission". An Access Point Provider is enabled "to facilitate real-time invoice exchange, validation, and transmission in accordance with compliance standards", including "handling encrypted data transfers and verifying invoices against NRS requirements".

Read that second definition once more if you have a Peppol background. It is a national role inside a clearance platform, and it shares nothing but a name with the four-corner term.

The order of the gates

1. Business profile on the e-invoicing portal — industry classification, reporting method, the ERP in use, turnover, notification preferences and exchange framework.
2. Service level agreement — reviewed and accepted.
3. Service provider registration form — this is where the System Integrator or Access Point Provider designation is fixed.
4. Sandbox build and test, against the authority's own self-test pages.
5. Go-live: confirm onboarding status with support, pass an integration review with the authority's engineer, execute the agreements and settlement account, swap sandbox keys for production keys, and move the callback and webhook URLs and the base URL across together.

The certification tests are three web pages

There is no downloadable test pack. The authority publishes three interactive self-test pages — invoice validation, invoice decryption and QR code validation — and the website itself is the harness. Validation takes an invoice file and reports whether it satisfies the schema and the business rules. Decryption proves you can read back an invoice the platform issued. QR validation confirms your signature resolves to the right invoice and the right issuer. Passing all three is what makes a provider eligible for the public approved-provider listing, so keep your own evidence — inputs, responses and screenshots — because the record the authority keeps is its own.

What should a supplier do now?

Decide whether you will connect directly or through a provider, get the business registered and its service identifier issued, then build to the documented schema rather than to whatever the sandbox tolerates. Test the whole lifecycle rather than validation alone, and keep the cleared originals.

• [ ] Confirm your own position from the authority's notices and the message addressed to your TIN — not from a summary.
• [ ] Decide the route: your own registration, or a registered System Integrator or Access Point Provider.
• [ ] Register the business and record the service identifier it is issued.
• [ ] Download the business's own cryptographic keys, and check the certificate is not the sample value from the documentation.
• [ ] Map your ERP to the documented schema, with the classification code on every line.
• [ ] Pull the reference code lists from the platform rather than hard-coding them.
• [ ] Compose the invoice reference number as invoice number, service identifier and date.
• [ ] Stand up the webhook endpoint before you need it: POST, 200, idempotent, logged.
• [ ] Implement acknowledgement and payment-status updates, not just validate and sign.
• [ ] Archive the cleared invoice and its reference number for the retention period Nigerian tax law requires of you.
• [ ] Subscribe someone to the changelog, and put the three-month grace window in your release calendar.

What does GoRoute provide for Nigeria?

We have built the Merchant-Buyer Solution integration and exercised it end to end against the authority's sandbox: validate, sign, QR generation, invoice-reference signature validation, encrypted download and decryption, and webhook delivery received from the authority's own dispatcher. That work was completed and evidenced in June 2026.

GoRoute also operates a certified Peppol Access Point and SMP for the markets that use Peppol — which, as this article has laboured, Nigeria does not. The two capabilities sit side by side in one API rather than in one network, and that is the honest way to describe it.

What is on our Nigeria e-invoicing page is the local picture. Book a demo if you want the integration walked through against your own taxpayer population.

Sources: the Nigeria Revenue Service e-invoicing documentation at einvoice.nrs.gov.ng/docs — endpoints, schema, roles, onboarding and certification, read at version 1.1 in May and June 2026; the Federal Inland Revenue Service; and GoRoute's own end-to-end integration testing against the platform's sandbox, May–June 2026.