Billing and Safe Retries

Invoice signing is the only billable Gateway operation. Your top-level business in Duplo Dashboard pays the current NGN signing fee for every represented business on its approved domain. The caller cannot choose the payer wallet, fee amount, fee destination, state, or mode.

Validation, NRS resource reads, entity and recipient lookups, health checks, transmission, represented-business onboarding, and Stored invoice reads do not create a Gateway signing charge.

Pass-through billing sequence

The public error is intentionally bounded so dependency details and internal billing identifiers do not leak.

{
  "message": "Invoice signing failed",
  "traceId": "req-018f0f56-f5f5-7c98-a21a-4a03c11a85b1"
}

{
  "message": "Invoice signing outcome is unconfirmed and requires reconciliation",
  "traceId": "req-018f0f56-f5f5-7c98-a21a-4a03c11a85b1"
}

Stored-mode billing

202 Accepted in Stored mode is not a billing event. It means the command and invoice record were accepted for asynchronous processing.

The processor validates the invoice first, then creates the signing debit immediately before NRS signing. It records the resulting NRS and billing state on the Stored invoice. A validation failure before sign is not billed. Poll GET /invoices/{invoiceId} until the record is terminal; do not infer sign success from the intake response or elapsed time.

Inspect firsRejectionReason whenever Stored processing ends at created / null after validation or rejected / rejected after signing/billing work. Keep the invoice ID and request trace. Do not create a replacement until you understand whether the original IRN may already exist; the current Gateway does not expose an edit/resubmit command for that record.

Design stable idempotency keys

Use one key for one logical command. Keys on Gateway management commands must be 8 to 128 characters long and use only letters, digits, dots, underscores, colons, and hyphens.

onboard:<customer-id>:v1
qr-material:<gateway-sub-business-id>:2026-08
stored-sign:<erp-invoice-id>:v1
stored-transmit:<duplo-invoice-id>:v1
pass-sign:<erp-invoice-id>:attempt-1

Keep the key in the same durable row as your invoice or onboarding command. Never generate it inside a network retry loop.

For Stored intake, idempotency also binds the approved domain configuration, its canonicalized domain label, the current test/live state, the mode version, the represented business, and the recursively canonicalized invoice body. Reordering JSON object keys does not change the fingerprint; changing a value or reordering an array does.

For Pass-through signing, Duplo also identifies the billing attempt by business, domain, IRN, and x-attempt-number. Re-sending the same logical attempt keeps both headers unchanged. After a conclusively failed or reversed attempt, a separately authorized attempt must use the next positive attempt number and a new stable idempotency key. Changing only the key can still return 409. Never advance either value for an unconfirmed outcome.

Retry decision table

A practical backoff policy

For read-only polling, start around one second, double up to a reasonable ceiling such as 30 seconds, add jitter, and enforce a total workflow deadline. Retry-After, when supplied, takes precedence. Stop on a terminal invoice state or a customer-visible 4xx that requires input.

Do not apply this generic policy to a Pass-through sign. A transport error after a debit is not evidence that NRS did nothing.

Status guide

An ordinary proxied NRS route can return an NRS status and body that is not in this table. Protected and management routes can return a Gateway error instead. See NRS API response ownership.

Reconcile an unconfirmed sign

When a Pass-through sign returns the unconfirmed 502:

1. Freeze automatic sign retries for that IRN and represented business.
2. Persist the exact request bytes, IRN, gatewaySubBusinessId, idempotency key, resolved attempt number (1 when omitted), request time, and returned traceId.
3. Check your own response/archive first. If the original success was stored elsewhere, use it.
4. Use an authoritative NRS lookup appropriate to the signed IRN and preserve that response. NRS owns the lookup schema, so do not treat a missing optional field as proof that signing failed.
5. Contact Duplo with the support packet below. Wait for the billing/NRS outcome before starting a new sign attempt.

Do not send internal billing identifiers; the public traceId is sufficient for Duplo to correlate the attempt.

Support packet

Provide:

• Gateway hostname and test/live state, but never the complete API key.
• UTC timestamp and your x-request-id.
• Returned traceId, HTTP status, and sanitized response body.
• IRN and gatewaySubBusinessId.
• Idempotency key and attempt number.
• Mode and mode version shown in your approved domain configuration.
• Whether you observed a wallet movement and any authoritative NRS lookup result.

Remove passwords, private keys, Duplo Dashboard secret keys, full API keys, customer personal data, and raw invoice line data unless Duplo asks for it through an approved secure channel.