NRS Invoice GatewayNRS Invoice Gateway
Onboard your business, represent NRS-registered issuers, and run compliant e-invoicing from one Duplo Gateway integration.
Duplo's NRS Invoice Gateway gives a system integrator one approved domain for connecting its software to the Nigeria Revenue Service (NRS) e-invoicing APIs. The Gateway keeps each represented issuer isolated and bills your top-level business (your Duplo Dashboard account) only when an invoice reaches the signing route.
These pages document NRS, the regulator currently enabled for customer use. The NRS API stays the authority for its regulatory fields and resource values, so keep the NRS e-Invoicing documentation, version 1.1.6 open alongside this guide.
The short version
Use the API key generated in Duplo Dashboard on your approved Gateway domain, and add the represented business ID for invoice operations. Every NRS call is unbilled except the invoice signing route; see Billing and safe retries for the unconfirmed-outcome exception.
Understand the actors
Four parties touch every signed invoice. Knowing which one holds a given credential, identity, or responsibility tells you where to look when something fails, and what your own system still has to store.
| Actor | What it owns | What it does not own |
|---|---|---|
| Your top-level business | Gateway domain, API key, NGN wallet, represented-business mappings, and the signing fees they incur | Any represented business's NRS taxpayer identity |
| Represented business | NRS taxpayer identity, TIN, IRN template, and optional QR material | A Duplo Dashboard login, API key, or payer wallet of its own |
| Duplo | Tenant routing, fee capture and reversal, Stored processing, and webhook delivery | The NRS account itself, its registration, or its standing |
| NRS | Taxpayer registration, IRN rules, validation, signing, transmission, and resource catalogs | Gateway availability, retry behavior, or signing fees |
The represented business may be your own legal entity or a client whose invoices your software produces. In both cases, the represented business must already be active in NRS and must link Duplo as its e-invoicing application before Gateway onboarding.
End-to-end journey
Two flows take you from a new Duplo Dashboard account to a signed invoice at NRS. The first runs while you set the integration up. The second runs every time your software issues a document.
Set up the Gateway
Complete these four steps before your first invoice. Step 4 repeats for each new represented business you take on, and steps 2 and 3 repeat when you move a domain between test and live, which follows the go-live release path.
Open Duplo Dashboard
Create a business account or sign in to an existing active business.
Create access
Choose test or live state, generate an API key, and request a Gateway domain.
Complete approval
Duplo reviews the domain, fee readiness, and Pass-through or Stored mode.
Onboard issuers
Verify every represented business against NRS and retain its Gateway ID.
Process every invoice
This is the runtime path your software repeats for each document. Your approved mode decides how the validate and sign steps behave: Pass-through returns the NRS result synchronously, while Stored accepts the invoice and validates, bills, and signs it afterward.
Build the invoice
Use current NRS resource codes and the payload required by your approved mode.
Validate
Validate directly in Pass-through, or let the Stored processor validate after acceptance.
Sign
The signing route performs the only billable Gateway operation.
Deliver and monitor
Transmit to the receiver, poll Stored status, and process inbound webhooks.
Choose your integration mode
Your domain is approved in exactly one mode. The choice changes the request body and response behavior of the same public signing URL.
Pass-through
Send the NRS wire payload, wait for NRS synchronously, and store the returned result in your own system. Best when you already own the invoice ledger and worker/reconciliation controls.
Stored
Send Duplo's invoice input, receive 202 Accepted, and let Duplo persist,
validate, bill, and sign asynchronously. Best when you want a durable
invoice record and status API.
Both modes call the same signing URL, so the difference shows up in what you send, what you get back, and where the invoice lives afterward. Check each row below against your own system before you request approval, because the mode is fixed for the life of the domain.
| Concern | Pass-through | Stored |
|---|---|---|
| Request body | NRS invoice document | Duplo invoice intake document |
| Validation | Your explicit Gateway call | Processor-managed after acceptance |
| Signing response | Synchronous NRS-format response | 202 Accepted with a Duplo invoice ID |
| Billable action | Sign | Sign, once the processor reaches it |
| Transmission | Raw NRS IRN path | Duplo invoice-ID path |
| Status reads | Your own store and NRS reads; no Duplo endpoint | Duplo list and per-invoice status reads |
| Invoice stored by Duplo | No | Yes |
Mode is server-controlled
Do not add a mode, business state, parent business, domain, wallet, or fee to an invoice request. The Gateway resolves these values from the approved hostname and current API key. Changing mode or moving between test and live requires a controlled drain and reapproval.
Base URLs and placeholders
Examples use these placeholders:
Dashboard: https://dashboard.tryduplo.com
Gateway base: https://<your-label>.invoice.tryduplo.com
API key: <publicKey from Duplo Dashboard>
Issuer ID: <gatewaySubBusinessId returned by POST /sub-businesses>Test and live use the same host shape. The current state of your top-level business and the approved domain state select the NRS environment. Never select an NRS base URL in a customer request.
Prerequisites
Have the following ready:
- A top-level business in Duplo Dashboard that is active and activated for e-invoicing.
- A user role allowed to manage API keys and NRS settings, with two-factor authentication enabled for key generation.
- An active NGN business wallet with enough balance for signing fees.
- For every represented business: an active NRS account, transient NRS portal credentials, and a usable IRN template. Keep its TIN ready only when the NRS entity has multiple active businesses and you need to select one. NRS QR material is optional and can be added later.
- An HTTPS webhook endpoint if you want inbound-invoice notifications.
- A secure store for the Duplo Dashboard API key, represented-business mappings, idempotency keys, invoice responses, and support trace IDs.
Start here
The four cards below are in the order you would work through them. Each one opens the page that covers that step in full.
Set up your top-level business (Duplo Dashboard Account)
Follow the new-business or existing-business path and confirm the account is eligible.
Request the Gateway domain
Generate the right state-bound key, choose a domain label, and understand approval.
Onboard a represented business
Verify the NRS identity, retain its Gateway ID, and optionally store the NRS material used for QR generation.
Review the NRS context
See common NRS paths and response envelopes, then use NRS's versioned reference for the complete contract.
How is this guide?
Last updated on