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 information reads, 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.

{
  "type": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_SIGN_REJECTED",
  "title": "Invoice signing was rejected",
  "status": 422,
  "detail": "The regulator rejected signing and compensation was confirmed.",
  "instance": "urn:duplo:request:01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "code": "GW_SIGN_REJECTED",
  "requestId": "01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "timestamp": "2026-09-15T12:34:56.789Z",
  "action": {
    "code": "CORRECT_SIGNING_REQUEST",
    "description": "Correct the documented validation issue before starting a new attempt.",
    "documentation": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_SIGN_REJECTED"
  },
  "retry": {
    "strategy": "AFTER_CORRECTION"
  },
  "message": "The regulator rejected signing and compensation was confirmed.",
  "statusCode": 422,
  "path": "/api/v1/invoice/sign"
}

{
  "type": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_SIGN_OUTCOME_UNCONFIRMED",
  "title": "Signing outcome is unconfirmed",
  "status": 502,
  "detail": "The regulator result could not be confirmed and signing may have occurred.",
  "instance": "urn:duplo:request:01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "code": "GW_SIGN_OUTCOME_UNCONFIRMED",
  "requestId": "01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "timestamp": "2026-09-15T12:34:56.789Z",
  "action": {
    "code": "CHECK_OPERATION_STATUS",
    "description": "Do not resubmit or use a new key; contact support with the request ID.",
    "documentation": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_SIGN_OUTCOME_UNCONFIRMED"
  },
  "retry": {
    "strategy": "CONTACT_SUPPORT"
  },
  "message": "The regulator result could not be confirmed and signing may have occurred.",
  "statusCode": 502,
  "path": "/api/v1/invoice/sign"
}

These are Gateway-generated failures and use application/problem+json. An eligible direct NRS call preserves an NRS-owned response only when NRS succeeds with 2xx; Gateway discards every NRS non-2xx body and maps it to a safe GW_* failure. See Handle Gateway error responses for handling rules and the Gateway error code reference for every stable code.

Pass-through transmission safety

Transmission is not billed, but it is still an external mutation. Before POST /api/v1/invoice/transmit/{irn} can reach NRS, Gateway obtains a durable Spend claim bound to the tenant, state, domain, represented business, IRN, idempotency identity, request hash, and a public operationId. Only a newly claimed operation may be dispatched to NRS.

An existing claim can resolve as in_progress, succeeded, rejected, or unknown. Gateway must not call NRS again for any of those dispositions. An in-progress or recorded outcome returns 409 GW_TRANSMIT_ATTEMPT_ALREADY_PROCESSED with the original operationId. A timeout, transport break, provider 5xx, malformed result, or expired in-flight claim that cannot prove the NRS outcome returns 502 GW_TRANSMIT_OUTCOME_UNCONFIRMED with that operation ID.

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.

Persist the onboarding idempotency key, immutable gatewaySubBusinessId, and complete current nrsIdentity together. Use gatewaySubBusinessId in Gateway headers and represented-business paths. Use firsBusinessId / nrsIdentity.nrsBusinessId as the current NRS business_id in future Pass-through invoice bodies. These values initially match, but a reviewed migration can advance the NRS mapping without changing the Gateway ID. A completed replay, the list endpoint, and GET /sub-businesses/{gatewaySubBusinessId} must return the same active identity version. If identity fields change without a corresponding reviewed version, stop and contact support instead of signing.

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 502 GW_SIGN_OUTCOME_UNCONFIRMED:

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 requestId.
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 requestId is sufficient for Duplo to correlate the attempt.

Reconcile an unconfirmed transmission

When a Pass-through transmission returns 502 GW_TRANSMIT_OUTCOME_UNCONFIRMED:

1. Freeze transmission retries for that IRN and represented business.
2. Retain the original requestId, operationId, idempotency key, request time, and response.
3. Check an authoritative NRS lookup and your own delivery archive, but do not treat an absent optional field as proof of failure.
4. Contact Duplo so the durable transmission claim can be reconciled. Do not create a new key while its disposition is unknown.

Support packet

Provide:

• Gateway hostname and test/live state, but never the complete API key.
• Returned UTC timestamp, requestId, HTTP status, and stable code.
• A sanitized response body and public operationId whenever the response contains one.
• 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.