Go-Live Checklist

Prove your NRS Invoice Gateway integration in test state, run the failure drills, and cut over to live as a controlled release.

Use test state to prove your whole integration, including how it handles failures, then move to live as a separate, controlled release. A successful sign in test isn't enough on its own. You also need durable mappings, billing recovery, delivery handling, and security controls.

This checklist follows that order: prove your integration in test, run the failure drills, cut over to live, then watch the signals after launch.

Prove your integration in test

Work through each group in test state. Your progress is saved in this browser.

Account and credentials

Your top-level business is active, activated for e-invoicing, and its compliance is accepted.

API management is enabled, and the integration role has only the key, settings, and NRS setup permissions it needs.

The NGN wallet for the target state is active and funded for expected signing volume plus headroom.

Finance knows that your top-level business pays the signing fee for every represented business.

Your API key was generated in the same state as the domain approval, and it is the only credential you send, as x-api-key.

Credentials live in a secrets manager, scoped by environment and service, never in source control or logs.

Clients call the exact hostname https://<label>.invoice.tryduplo.com, never override Host, and never call NRS directly.

ipWhitelisted lists every caller egress address, or is deliberately empty, and a test shows that a non-matching address receives 403.

Your Duplo contact has confirmed NRS Invoice Gateway availability for the target environment.

Represented businesses

Each business is active in the target NRS environment and has linked Duplo as its application.

Each NRS entity has exactly one active business, or onboarding sends the TIN that selects one.

You store each business's onboarding response as opaque strings: gatewaySubBusinessId for routing and firsBusinessId as the Pass-through business_id.

No stored ID is an old Duplo UUID. Any you find are replaced with the current gatewaySubBusinessId from GET /sub-businesses.

GET /sub-businesses, paginated to the end, matches every business you expect in this state and mode.

NRS passwords used for onboarding never reach job payloads, logs, traces, or durable storage.

If you need invoice QR codes, both QR values are stored and a signed test invoice shows that they work.

cryptoVersion: 0 is a valid production state. It means no QR material is stored, and QR generation never blocks onboarding, signing, or transmission.

Invoice data

Your IRN builder follows each business's current NRS template, checked against NRS before launch, and produces stable, unique IRNs.

Supplier TIN and business_id always come from the same represented-business mapping.

Totals, taxes, allowances, charges, currency, and dates are tested at decimal and rounding boundaries.

Credit and debit notes carry the original-invoice billing reference, and each line has a matching product or service classification.

NRS resource codes are fetched and cached for a bounded period, not frozen in code.

Your client preserves or safely ignores unknown fields in NRS responses.

Validate a set of representative invoices before your first sign test:

The smallest and largest invoices you expect, with multiple lines and tax subtotals.
A commercial invoice plus every note type your product supports.
A receiver that is connected and one that is unavailable.
An invalid TIN, an outdated resource code, a bad total, a duplicate IRN, and a malformed body.
Unexpected NRS responses: additive fields, changed types, malformed success JSON, 202, 204, 401, 403, 429, a redirect, a timeout, and an oversized body.
A payload near your size limit. The Gateway's default limit is 10 MiB.

Your mode

Your deployment should record the approved mode and its version, and alert on a state or mode conflict instead of retrying. Then check the list for your mode.

Pass-through

Your system stores the exact NRS request and response, because Duplo doesn't store Pass-through invoices.

Validate and sign use the same document and IRN.

Every sign has a stable idempotency key and attempt number that retries keep unchanged, and you keep the Gateway request ID.

Only HTTP 2xx with body code: 201 and data.ok: true counts as sign success.

A 409 sign replay goes to recovery, never to a new random key.

Lookup and transmission use the same represented-business ID and signed IRN.

GW_SIGN_OUTCOME_UNCONFIRMED and GW_TRANSMIT_OUTCOME_UNCONFIRMED freeze that IRN and open reconciliation, keeping any operationId.

Stored

Every invoice customer exists in the same state, has the invoice module, and has a TIN, email, address, city, country, and postcode before intake.

Requests send the Stored invoice document, not the NRS document.

202 Accepted counts as intake only, never as sign success, and invoiceId is saved before your caller sees success.

Polling uses exponential backoff, jitter, and a deadline, and stops at an end state.

Transmission runs only after the invoice is signed, with its own stable idempotency key.

Your UI tells transmitted, not_sent, and rejected or unknown delivery apart.

Webhooks

Skip this group if inbound receipt isn't in your launch scope. Inbound receipt needs separate approval from Duplo for each environment, so read the webhooks guide before you include it.

The webhook URL is a hard-to-guess public HTTPS URL on the default port, saved on the current-state API key.

GET on the URL returns 2xx without redirecting to a login page.

POST saves the event and x-duplo-delivery-id before returning 2xx, and a uniqueness constraint drops duplicate delivery IDs.

Test and live events go to separate data and workers.

Unknown events and fields don't crash the endpoint.

You read the invoice back before acting on an event, because the webhook request itself is unsigned.

You can recover missed notifications by listing and reading invoices.

Security

Requests carry only documented headers: never Dashboard secret keys, NRS passwords, private keys, or server-controlled values such as parent IDs, wallets, state, or mode.

TLS verification is on, and no code accepts an arbitrary certificate.

Logs and error reports redact API keys, passwords, QR material, invoice bodies, and personal data.

Support exports are sanitized and sent through an approved secure channel.

You have rehearsed API key rotation, QR material replacement, a leaked webhook URL, and staff offboarding.

Alerts fire on authentication spikes, 409 state drift, debit declines, sign 502, long Stored pending states, and webhook failures.

Run the failure drills

Prove these behaviors in an authorized test environment:

Drill	Expected system behavior
Insufficient wallet balance	NRS is not called; the invoice stays recoverable; operators see `402 GW_BILLING_WALLET_DECLINED` guidance
Invalid NRS document	The rejection is recorded; no blind retry loop starts
Pass-through success	One charge and one durable sign result are linked to the IRN, idempotency identity, and request ID
Duplicate Pass-through attempt	`409` enters original-result recovery; no random key is generated
`GW_SIGN_OUTCOME_UNCONFIRMED`	Automation freezes that IRN and opens a reconciliation case with `requestId`
Stored intake response lost	The exact request is resent with the same key and resolves to one invoice
Stored invoice stays pending	The poller backs off and alerts after its own deadline without resubmitting
Transmission timeout	The system reads the current state and retries delivery only; it never signs again
Rate limit	The caller backs off with jitter, caps concurrency, and honors `Retry-After` when present
`GW_REQUEST_BODY_TIMEOUT`	The caller sends the complete body promptly and keeps the same mutation identity
`GW_GATEWAY_CAPACITY_EXCEEDED`	The caller honors `Retry-After` and doesn't fan out to another host or key

Finance and engineering should also be able to trace any sign in a chosen period through this chain:

Reconciliation chain

Your sign commands
↔ Gateway request ID/idempotency/IRN
↔ NRS result or reconciliation state
↔ Duplo signing fee movement/reversal

Cut over to live

Moving to live is a controlled process with Duplo, not a dashboard toggle:

Stop test invoice producers and reconcile every in-flight sign, billing attempt, Stored invoice, and unresolved transmission.
Coordinate with Duplo to place the domain in draining and complete the Duplo Dashboard state change. Expect the old key, represented-business access, and domain approval to stop working.
Sign in again, confirm that Duplo Dashboard shows live, and generate a live API key.
Configure the live webhook and caller IPs on that key. If you rely on IP restriction, confirm that Duplo has enabled enforcement in live.
Wait until the domain status is approved in live with the expected mode and version.
Onboard each represented business in live and save the new mappings.
Run the connection check, NRS resource reads, a recipient lookup, and a validation before the first billed sign. These checks don't prove that the wallet is funded or that a mapping is correct.
Send one controlled invoice, keep its full audit trail, transmit it, and reconcile its signing fee.
Ramp volume in stages while you watch billing, NRS latency and errors, Stored queue age where applicable, and webhook delivery.

Do not bypass reapproval

A state or mode mismatch returns 409 by design. Don't change the hostname, forge state or mode fields, reuse a revoked key, or call NRS directly to work around it. Finish the controlled domain workflow and preserve in-flight reconciliation.

After launch

Decide who owns each signal before launch:

Signal	Owner	Immediate action	Escalation data
`401` surge	Security/integration	Verify secret deployment and key status; stop rotation loops	Host, state, timestamps, key prefix/last four only
`409` state or mode drift	Platform owner	Pause intake and read the current domain configuration	Domain status, mode/version, request ID
`GW_BILLING_WALLET_DECLINED`	Finance + operations	Pause billed intake; check wallet and account readiness	Request ID, IRN, represented-business ID, UTC time, sanitized error
`GW_SIGN_OUTCOME_UNCONFIRMED`	Reconciliation owner	Freeze the IRN and preserve evidence; don't re-sign	Request ID, operation ID when present, idempotency key, NRS lookup
`GW_TRANSMIT_ATTEMPT_ALREADY_PROCESSED`	Reconciliation owner	Use the returned operation ID; don't bypass the existing claim	Request ID, operation ID, IRN, idempotency key
`GW_TRANSMIT_OUTCOME_UNCONFIRMED`	Reconciliation owner	Freeze transmission and reconcile its claim; don't resend	Request ID, operation ID, IRN, idempotency key, NRS lookup
Stored pending beyond your SLO	Operations	Keep polling bounded and open an investigation	Invoice ID, IRN, represented-business ID, timestamps
Webhook outage	Application owner	Restore a 2xx receiver and reconcile through the invoice API	Delivery and invoice IDs, outage window
NRS resource rejection	Tax/integration	Refresh the current catalog and review your payload mapping	NRS status, resource version and time

For escalation, send Duplo the billing support packet. Never include full credentials or private cryptographic material.

On this page