Go-Live Checklist

Validate business, domain, NRS, billing, security, retry, and operational readiness before sending live invoices.

Use test state to prove the complete customer and failure journey, then treat live as a separate controlled launch. A successful NRS sign alone is not enough: the integration also needs durable mappings, billing recovery, delivery handling, security controls, and an operator runbook.

Release path

Prove test
Exercise the approved mode, NRS validation/signing, billing failures, retries, transmission, and inbound processing.
Drain
Have Duplo place the domain in draining and clear all non-terminal billing, Stored, and transmission work.
Change state
Complete the controlled Duplo Dashboard state switch, sign in again, and create the target-state credential.
Reapprove
Configure the new credential and wait until the domain is approved in the target state and mode.
Re-onboard and ramp
Onboard represented businesses only after approval, then start with monitored traffic.

1. Business readiness

The top-level business in Duplo Dashboard is active and activated for e-invoicing.

Compliance is complete and accepted.

API management is enabled for the business.

The integration user role has only the required key, settings, and NRS setup permissions.

The intended test or live state is visible after a fresh sign-in.

The state-specific NGN payer wallet is active and funded for expected signing volume plus operational headroom.

Finance understands that the top-level business in Duplo Dashboard pays sign charges for every represented business.

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

2. Credential and domain readiness

The active API key was generated in the same state as the domain approval.

Only the API key is sent as x-api-key to Gateway.

The Duplo Dashboard secret key and all complete credentials are stored in an approved secrets manager, not source control or logs.

The exact hostname is https://<label>.invoice.tryduplo.com; clients do not override Host or use an NRS origin directly.

Domain status is approved, not pending, pending_reapproval, draining, rejected, or disabled.

The approved mode (PASSTHROUGH or STORED) matches the body, response, storage, and transmission implementation you tested.

Your deployment records the observed mode version and alerts on a state/mode conflict instead of retrying.

The credential's ipWhitelisted setting contains every intended caller egress address, or is deliberately empty for unrestricted access. A production-equivalent edge test proves that an allowed address succeeds and that a missing, malformed, or non-matching trusted address returns 403.

Run a non-billable host check:

curl https://acme.invoice.tryduplo.com/health

Host health response

{ "status": "ok" }

Then run an authenticated, unbilled NRS self-health check:

curl \
  --url https://acme.invoice.tryduplo.com/api/v1/invoice/transmit/self-health-check \
  --header 'x-api-key: pk_live_replace_with_your_key'

Do not use either health response as proof that a wallet is funded or a represented business is correctly mapped.

Also configure deployment probes deliberately: /health/live is process liveness, while /health/ready covers local initialization and the Redis safety dependency. A shared Spend or NRS outage does not deliberately make every Gateway pod unready. Duplo operators use the protected, cached /health/dependencies view for dependency, circuit, capacity, processor-heartbeat, and recovery state; customers must not treat that route as a live NRS probe.

3. Represented-business readiness

For every issuer, maintain a durable mapping such as:

Represented-business mapping to retain

{
  "yourCustomerId": "erp-customer-1042",
  "gatewaySubBusinessId": "nrs-business-demo",
  "firsBusinessId": "nrs-business-demo",
  "nrsIdentity": {
    "entityId": "entity-demo",
    "entityReference": "entity-reference-demo",
    "nrsBusinessId": "nrs-business-demo",
    "businessName": "Acme Retail Limited",
    "tin": "12345678-0001",
    "irnTemplate": "{{invoice_id}}-2A3A045D-{{YYYYMMDD}}"
  },
  "businessState": "live",
  "cryptoVersion": 0
}

The NRS taxpayer is active in the target environment and has linked Duplo as its application.

The NRS entity has exactly one active business, or onboarding supplies the exact TIN needed to select one.

The IRN template returned in the stored nrsIdentity snapshot has been checked against current NRS data before launch.

The canonical gatewaySubBusinessId from onboarding is stored and backed up as an opaque string, not validated as a UUID.

The complete nrsIdentity is stored; immutable gatewaySubBusinessId is used for Gateway routing, while the current firsBusinessId / nrsIdentity.nrsBusinessId value is used as NRS business_id in Pass-through payloads.

If invoice QR codes are required, both NRS QR values are stored and a signed test invoice proves that the runtime public key works.

Operations can add or replace optional QR material without treating it as an onboarding, signing, or transmission readiness gate.

NRS passwords used during onboarding are removed from job payloads, logs, traces, and durable application storage.

The represented business has no assumed Duplo Dashboard login, API key, or payer wallet in your design.

An authenticated GET /sub-businesses/{gatewaySubBusinessId} returns the expected active mapping without NRS credentials, and operations understand that it is a persisted snapshot rather than a live NRS check.

GET /sub-businesses?page=1&limit=50 has been paginated to completion and reconciled against every represented business expected in this parent/domain/state/current-mode scope.

Any UUID returned by the previous contract has been resolved through detail or list, replaced with the current immutable gatewaySubBusinessId, and removed from client-side UUID validation.

cryptoVersion: 0 is a valid production state: it means no QR material is stored. Gateway stores supplied values opaquely and discovers an unusable public key only when QR generation is attempted. QR generation is best-effort and must not be used as proof that onboarding, signing, or transmission succeeded.

4. Invoice-data readiness

Your IRN builder follows each represented business's current NRS template and produces stable, unique references.

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

Monetary totals, taxes, allowances, charges, currency, dates, and line extensions are tested with decimal/rounding boundaries.

Credit/debit notes carry the required original-invoice billing reference.

Product and service classifications are mutually correct for each line.

NRS tax, HSN, service, and quantity resources are fetched and cached for a bounded period instead of frozen in code.

Unknown additive NRS response fields are preserved or ignored safely.

Logs and error reporting exclude full invoice bodies and unnecessary personal data.

Validate representative invoice fixtures before any sign test:

Smallest and largest expected invoices.
Multiple line items and multiple tax subtotals.
Commercial invoice plus every note/type your product supports.
Receiver connected and receiver unavailable.
Invalid TIN, expired resource code, bad total, duplicate IRN, and malformed body.
Additive NRS fields, changed types, malformed success JSON, unexpected 202, empty 204, provider 401/403, 429, redirect, timeout, and oversized response fixtures.
Payload near your configured application limit; Gateway's default buffered ceiling is 10 MiB.

5. Mode-specific readiness

Pass-through

Your system stores the exact NRS request and response durably because Gateway does not create a customer-visible invoice row.

Validate and sign use the same canonical document and IRN.

Every sign has a stable idempotency key and positive attempt number; permitted network retries preserve both attempt identity values, and your system retains the Gateway-generated request ID.

Your client recognizes only HTTP 2xx plus body code: 201 and data.ok: true as sign success.

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

GW_SIGN_OUTCOME_UNCONFIRMED freezes signing for the IRN and opens reconciliation.

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

GW_TRANSMIT_OUTCOME_UNCONFIRMED freezes delivery for the IRN, preserves operationId, and opens reconciliation instead of creating a new key.

Stored

Every invoice customer exists in the same parent/state, has the invoice module, and contains NRS-ready TIN, email, address, city, country, and postcode metadata before intake.

The request uses the Duplo Stored DTO, not the raw NRS wire document.

202 Accepted is recorded as intake acceptance, never as sign success.

The returned invoiceId is persisted before your caller receives success.

Polling uses exponential backoff, jitter, a deadline, and terminal-state handling.

Invoice-ID transmission is called only after the invoice is signed and uses its own stable idempotency key.

Your UI distinguishes transmitted, not_sent, and rejected/unknown delivery outcomes.

6. Billing and failure drills

Prove these behaviors in an authorized test environment:

Drill	Expected system behavior
Insufficient wallet balance	NRS is not called; invoice stays recoverable; operator sees `402 GW_BILLING_WALLET_DECLINED` guidance
Invalid NRS document	Validation/sign rejection is recorded; no blind retry loop starts
Pass-through success	One charge and one durable sign result are correlated to IRN, idempotency identity, and request ID
Duplicate Pass-through attempt	`409` enters original-result recovery; a random key is not generated automatically
Simulated `GW_SIGN_OUTCOME_UNCONFIRMED`	Automation freezes that IRN and creates a reconciliation case with `requestId`
Stored intake response lost	Exact request is resent with the same command key and resolves to one invoice
Stored worker remains pending	Poller backs off and alerts after its own service-level deadline without resubmitting
Transmission timeout	System reads current state and retries delivery only; it never signs again
Rate limit	Caller uses bounded jittered backoff and caps concurrency; honor `Retry-After` if a route supplies it
Slow or incomplete request body	Caller handles `GW_REQUEST_BODY_TIMEOUT`, sends the complete body promptly, and retains the same mutation identity
Gateway capacity full	Caller handles `GW_GATEWAY_CAPACITY_EXCEEDED`, honors `Retry-After`, and does not fan out to another host or key
Runtime routing loop	Gateway returns `508 GW_ROUTING_LOOP_DETECTED`; automation stops until the upstream route is corrected

Finance and engineering should be able to reconcile, for a chosen period:

Reconciliation chain

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

7. Webhook readiness

Inbound receipt is a separately approved launch scope

Do not use this checklist as proof that inbound NRS callbacks are enabled. Before you include inbound receipt in test or live scope, obtain Duplo confirmation that the environment has trusted-edge path proof, independent NRS sender authentication or an authoritative NRS source restriction, WAF/rate controls, and a proven callback timing and crash-recovery decision. The current handler completes NRS download/decrypt processing before acknowledging the callback and records caught processing failures without asking NRS to retry them. If those controls and a durable recovery path have not been certified, Duplo must leave the callback unregistered and your release must explicitly exclude inbound receipt.

The webhook URL is canonical HTTPS on the default port, publicly resolvable only to public addresses, high-entropy, and saved on the current-state API key.

GET reachability returns 2xx without redirecting to a login page.

POST persists x-duplo-delivery-id and the event before returning 2xx.

A database uniqueness constraint deduplicates delivery IDs.

Test and live events are processed by state-isolated data and workers.

Unknown events and additive fields do not crash the endpoint.

An authenticated invoice read matches invoice ID, IRN, represented business, state, and direction: inbound before irreversible processing; the team understands that read-back mitigates an unsigned event but does not authenticate its sender.

Operations can reconcile missed/dead-lettered notifications by listing and reading invoices.

See Verifying events for how an authenticated invoice read establishes invoice truth while the webhook request itself remains unsigned.

8. Security review

Public API keys are scoped in your secrets manager by environment and service.

Invoice requests contain only documented public headers and never include Duplo Dashboard secret keys, NRS passwords, or private keys.

Clients do not supply parent IDs, wallets, state, mode, or other server-controlled values.

TLS verification is enabled and no code accepts an arbitrary certificate for the Gateway/NRS connection.

Application logs redact API keys, passwords, NRS QR material, invoice bodies, and customer personal data.

Support exports are sanitized and use an approved secure channel.

API-key rotation, optional QR-material replacement, compromised webhook URL, and employee offboarding procedures are rehearsed.

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

The edge overwrites the configured trusted client-address header; Gateway carries it only over the authenticated internal authorization hop, and callers cannot influence IP allowlisting or distributed admission with X-Forwarded-For.

Deployment egress reaches only approved Spend, administrator, NRS, Redis, and Slack destinations, and startup rejects an upstream that targets Gateway itself.

Load tests prove that one noisy domain, slow request bodies, and slow dependencies cannot consume every worker or socket.

9. Production cutover

Stop test invoice producers and reconcile every in-flight sign, non-terminal billing attempt, Stored invoice, and unresolved transmission.
Coordinate with Duplo to place the approved domain in draining, prepare it for target-state reapproval, and complete the Duplo Dashboard state transition. Expect the prior key/refresh context, represented-business access, and domain approval to stop being usable.
Sign in again and generate a new live API key.
Configure the live webhook and intended caller IPs on that credential; if you rely on IP restriction, confirm that Duplo has enabled enforcement in live.
Wait until the domain reports approved in live with the expected mode/version.
Complete live represented-business onboarding and save the new state-bound mappings.
Run health, NRS resource, recipient lookup, and validation checks before the first billed sign.
Send one controlled invoice, persist its complete safe audit trail, transmit it, and reconcile the sign fee.
Ramp volume in stages while watching billing, NRS latency/error rate, Stored queue age where applicable, and webhook delivery.

Do not bypass reapproval

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

Operator runbook

Document these decisions 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 current domain configuration	Domain status, mode/version, request ID
`GW_BILLING_WALLET_DECLINED`	Finance + operations	Pause billed intake; check wallet/account readiness	Request ID, IRN, child ID, UTC time, sanitized error
`GW_SIGN_OUTCOME_UNCONFIRMED`	Reconciliation owner	Freeze the IRN and preserve evidence; do not re-sign	Request ID, operation ID when present, idempotency key, NRS lookup
`GW_TRANSMIT_ATTEMPT_ALREADY_PROCESSED`	Reconciliation owner	Use the returned operation ID; do not bypass the existing claim	Request ID, operation ID, IRN, idempotency key
`GW_TRANSMIT_OUTCOME_UNCONFIRMED`	Reconciliation owner	Freeze transmission and reconcile its durable claim; do not resend	Request ID, operation ID, IRN, idempotency key, NRS lookup
`GW_GATEWAY_CAPACITY_EXCEEDED`	Gateway operator	Check noisy-domain, process, Redis, socket, and dependency saturation; retain caller keys	Request IDs, route, domain hash, capacity snapshot
`GW_ROUTING_LOOP_DETECTED`	Platform/network	Stop retries and correct DNS, proxy, origin, or service discovery	Request ID, environment, configured target, route
Stored pending beyond SLO	Operations	Keep read-only polling bounded and open an investigation	Invoice ID, IRN, child ID, timestamps
Webhook outage	Application owner	Restore 2xx receiver, verify reachability, reconcile via invoice API	Delivery/invoice IDs and outage window
NRS resource rejection	Tax/integration	Refresh current catalog and review payload mapping	NRS status/body, resource version/time

Use the Gateway operations runbook for dependency, health, circuit, Slack, and recovery procedures, and the billing support packet for Duplo escalation. Never include full credentials or private cryptographic material.

On this page