Nigeria E-Invoicing Onboarding: A Step-by-Step Runbook

Connecting to Nigeria's e-invoicing platform is a clearance integration, not a network join. You register on the tax authority's platform, receive an API key and secret, build a UBL-derived JSON invoice, validate it, then sign it — and the platform returns the cleared invoice reference number that makes the document real, plus the material for its QR code. This runbook is the order we work in, with what breaks at each step, taken from the authority's developer documentation and from our own testing against its sandbox.

Step 0 — Check what you are actually connecting to

Before anything else: Nigeria does not run a Peppol network, and a plan built on that assumption fails at the first design review. There is no AS4 transport, no service metadata publisher to publish to, no service metadata locator to resolve, and no Peppol participant identifier. Those steps do not appear anywhere below because they do not exist here.

What exists instead is one central platform, reached over ordinary HTTPS with two headers. If you have arrived from a Peppol country, the mental model to bring is Saudi Arabia's clearance regime, described in our ZATCA e-invoicing guide — not Belgium's or Australia's. The full contrast, and why the shared phrase "Access Point Provider" causes so much confusion, is in FIRS e-invoicing Nigeria: the Merchant-Buyer Solution explained. For who has to do any of this and from when, see the Nigeria e-invoicing mandate.

Step 1 — Register, and decide which role you are registering in

Registration runs through the authority's e-invoicing portal in a fixed order, and each gate opens the next:

1. Business profile — 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 your designation is fixed.
4. Sandbox build and self-test against the authority's own test pages.
5. Go-live, which is Step 9 below.

The designation is a real decision, because the authority defines 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 the second definition twice 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.

A taxpayer that only wants to report its own invoices does not need either role. The documented changes of November 2025 allow a taxpayer to report directly with its own keys, using a reserved value in the integrator field. If that is you, skip the provider registration and go to Step 2.

Step 2 — Get the credentials, and get the right keys

Two separate things arrive from the dashboard, and confusing them costs a rejection.

API credentials. Every request carries x-api-key and x-api-secret headers — not a bearer token. Keys are issued per registered application, HTTPS is mandatory, and a compromised key is regenerated from the dashboard. Put both in a secret manager on day one; they will need rotating and they will need swapping again at go-live.

Cryptographic keys. Separately, under the account's cryptographic-keys page, you download a small JSON file holding a public key and a certificate. These are for the QR code in Step 6, and they are per business, not per provider.

The trap that fails a certification review. The documentation prints a sample key bundle. A QR built with it validates perfectly — and resolves to the documentation's own demo business rather than to your supplier. We hit exactly this: the QR verified, and the issuer it reported was the sample identity while the invoice named the real supplier. A reviewer caught it and rejected the submission. Check that the certificate value your dashboard returns is not the one printed in the public documentation. If it is, the account has no key of its own yet, and that is a question for the authority's support desk before you build anything on top of it.

Step 3 — Create the entity and the business, and capture the service identifier

The platform is hierarchical: an integrator holds entities, and an entity holds the taxpayer businesses whose invoices you submit. Until at least one business exists, signing has nothing to sign against.

• POST /api/v1/entity creates the entity. It needs a reference of your choosing and returns the entity identifier and an application reference.
• POST /api/v1/entity/{entity_id}/business creates the taxpayer business under it. It needs a reference, a name and a TIN, and returns the business identifier and an invoice-reference template.
• GET /api/v1/entity/{entity_id} returns the entity with its businesses attached.

That template is the thing to capture. It carries the eight-character service identifier assigned to the business, and it is what you will compose invoice reference numbers from for the life of the integration. Record it next to the business in your own database rather than in a ticket.

Use the real legal entity here. A business record left as a demo name with a placeholder TIN will surface later, in a rendered invoice or a QR verification, in front of someone assessing you.

Step 4 — Build the invoice payload

The invoice is a UBL-derived JSON document, up to two megabytes. Eleven fields are mandatory: 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 must carry a TIN and an email address.

Beyond the mandatory set, five details account for most of the rework:

• A classification code on every line — an HSN code for goods, an ISIC code for services. A generator that emits it for the first line and not the second produces a document that reads correctly and validates as an error. Our own first validation failure was exactly this.
• The invoice reference number is composed by you: invoice number, service identifier from Step 3, and date, joined with hyphens — {InvoiceID}-{ServiceID}-{YYYYMMDD}.
• invoice_kind is B2B, B2G or B2C, and it drives downstream behaviour: the QR code requirement is specific to the consumer case.
• State and local government area are required on the accounting parties, in the platform's own code values.
• Pricing carries a unit code and a base quantity. The documented changes of April 2026 made the price unit code mandatory, taken from the platform's own quantity-code list, alongside the base quantity.

Fetch the code lists rather than hard-coding them. The platform serves units of measure, currencies, countries, tax categories, payment means, service codes, invoice type codes, states and local government areas as read endpoints, and they move: withholding tax, stamp duty and exempted joined the tax categories in the documented changes of February 2026. A build that hard-codes reference data passes today and fails on the next revision.

Step 5 — Validate, then sign

This is the core of the integration and it is two calls in a fixed order.

Signing takes the same body as validation and requires that the document has already passed it. After signing, the invoice exists under its reference number and can be confirmed, downloaded in encrypted form, transmitted and updated.

Validate locally first. Structure, totals, the classification code on every line, the state and local-government values — check all of it in your own code before you spend a call on the platform. It is faster to debug and it keeps your quota for documents you believe are correct.

Step 6 — What to do when validation fails

Nothing goes forward, which is the point: a rejected invoice is not a cleared invoice with a warning attached, it is not yet an invoice at all. The platform answers HTTP 400 with an error object carrying four parts — a request identifier, the handler that rejected the document, a machine-readable detail naming the field, and a user-facing message.

Persist all four, together, against the document. The request identifier is what the authority's support desk asks for; the detail is what your engineers act on; the public message is the one you can show an accounts-payable clerk without translating it first. A retry queue that keeps only "failed" has thrown away the entire diagnosis.

Three patterns account for most lost time:

1. A missing per-line classification code, as above.
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 — a permissive sandbox today is not a promise about production tomorrow.
3. Discovering a schema change late. The authority's changelog is its own record of what has moved, and the stated policy is a three-month grace window before a breaking change is enforced. That window only helps a team that is reading it.

Step 7 — Produce the QR code

The platform does not hand you an image. The QR code is produced on your side, from material the dashboard gave you in Step 2:

1. Compose the payload: the invoice reference number with a Unix timestamp appended after a dot, together with the business's certificate.
2. Encrypt that payload with the authority's RSA public key, using PKCS#1 v1.5 padding.
3. Base64-encode the ciphertext. That string is the QR content.
4. Render it with any QR library.

Scanning it resolves back to the invoice reference and the issuing business — which is why the certificate must be that taxpayer's own, never a provider's and never the documentation's sample. The rule to carry into production is one line: a client taxpayer's QR is built with that client's certificate.

Step 8 — Wire the webhook before you need it

Transmission is asynchronous. The platform reports what happened through a webhook rather than in a response body, and teams that leave this to a later phase discover it during their first live day.

• Register the webhook URL in the service-provider portal. On registration the platform immediately dispatches a test notification to check reachability.
• The endpoint must accept POST and answer 200. Failures are retried and eventually suppressed.
• The payload is small: an invoice reference number and a message, one of TRANSMITTING, TRANSMITTED, ACKNOWLEDGED or FAILED.
• Notifications are stateless and event-driven. 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, so implement the receiver's acknowledgement call as part of this step rather than a later one.

Keep a separate webhook URL per environment, and log every delivery with its message and timestamp. When a counterparty says they never received an invoice, that log is the answer.

Step 9 — Payment status and VAT reporting

Clearance is not the end of the record. Payment status lives 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 — supplier and beneficiary identifiers, base amount, other taxes, the VAT calculated and the rate, which in the authority's own example payload is 7.5.

Wire both into the same event that updates your ledger. A payment status that is only correct in your own system is a reconciliation problem waiting for a quarter-end.

Step 10 — Pass the three certification tests, then go live

There is no downloadable test pack. The authority publishes three interactive self-test pages and the website itself is the harness:

Passing all three is what makes a provider eligible for the public approved-provider listing. The authority keeps its own submission record; keep yours too — inputs, responses and screenshots — because that is the evidence you will be asked for, and it is the pack a reviewer reads.

Then the go-live sequence, in this order:

1. Confirm onboarding status with the authority's support desk.
2. Pass the engineer's integration review.
3. Execute the agreements and the settlement account.
4. Swap sandbox API keys for production keys.
5. Move the callback URL, the webhook URL and the base URL across together — a production base URL still pointing at a sandbox webhook produces invoices nobody is told about.

One thing to check on the day, not on ours. When we tested in May 2026 the sandbox implemented the validate-and-sign core only, and the post-signing calls — confirm, transmit, report — were documented but returned not-found; by June the encrypted download and its decryption worked end to end for us. Which calls are deployed in the sandbox on the day you build is a question with a moving answer, so write client stubs that flip to live calls when the response changes, and verify against the sandbox rather than against this list.

Day-2 operations

The old version of this runbook told you to monitor transport metrics between access points. There are none. What actually needs watching:

• Daily — the rejection rate, grouped by the machine-readable detail from the error object, so a schema drift shows up as a spike in one field rather than as noise. And webhook deliveries: retries and suppressions are the early warning that your endpoint is failing.
• Weekly — sample five invoices end to end, from the ERP record through validation, signing, the reference number and the QR to the counterparty's acknowledgement.
• Monthly — reconcile cleared invoice reference numbers against your own ledger, and payment statuses on the platform against the ones in your system.
• Quarterly — key custody: who can reach the API secret and the cryptographic bundle, and when they were last rotated.
• Continuously — the authority's documented changes, with the three-month grace window written into your release calendar.

Cross-references

• What the platform is, in full — FIRS e-invoicing Nigeria: the Merchant-Buyer Solution explained.
• Scope and the dated rule changes — the Nigeria e-invoicing mandate.
• What we operate locally — our Nigeria e-invoicing page.
• The country-by-country picture — e-invoicing mandates 2026 tracker.
• One integration, several regimes — the multi-country e-invoicing API.

What we ship at GoRoute

We have built this integration and exercised it end to end against the authority's sandbox: entity and business onboarding, 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 Step 0 laboured — Nigeria is not. Both sit behind one API. Book a demo to walk the path above against your own systems.

Sources: the Nigeria Revenue Service e-invoicing documentation at einvoice.nrs.gov.ng/docs — onboarding gates, roles, authentication, invoice schema, QR generation, webhooks and the certification self-tests, read at version 1.1 in May and June 2026; the Federal Inland Revenue Service; and GoRoute's own sandbox testing and certification evidence, May–June 2026.