Sign or Store NRS Invoice

Billable operation whose request and response are selected by the domain's approved invoice-handling mode, not by a caller-supplied discriminator. Both modes require x-sub-business-id. PASSTHROUGH accepts PassthroughInvoiceSignInput, treats x-idempotency-key as optional in the current API version, debits synchronously, and returns the sanitized NRS HTTP 200 response; x-attempt-number and x-invoice-reference apply only to this mode. Unknown PASSTHROUGH post-debit outcomes return GW_SIGN_OUTCOME_UNCONFIRMED with operationId and must not be resubmitted. STORED accepts StoredInvoiceInput, requires x-idempotency-key, and returns HTTP 202 after durable intake; later processor failures are owned by Spend. Sending the body shape for the other approved mode is a validation error. OpenAPI cannot express a header that is required only for one server-selected body branch, so x-idempotency-key is structurally optional here but operationally mandatory in STORED mode.

Authorization

apiKey

x-api-key<token>

The API key generated for your business in Duplo Dashboard. The credential's ipWhitelisted setting is enforced end to end on the customer-facing custom-domain Gateway routes in this public contract. A trusted edge overwrites the configured client-IP header and Gateway carries that verified address over its authenticated internal hop; caller-supplied X-Forwarded-For values are never trusted. An empty IP allowlist permits any source. When an allowlist is configured, a missing, malformed, or nonmatching verified client address is rejected with HTTP 403.

In: header

Header Parameters

x-sub-business-id*string

Immutable gatewaySubBusinessId returned by onboarding/list. Gateway resolves it to the current audited NRS identity before dispatch.

Length1 <= length <= 255

x-idempotency-key?string

Optional in the current PASSTHROUGH API version. When supplied, use 8-128 allowlisted characters and preserve the same key for the same logical mutation. STORED sign requires this header.

Match^[A-Za-z0-9._:-]+$

Length8 <= length <= 128

x-attempt-number?integer

Positive safe integer for a PASSTHROUGH sign attempt; defaults to 1. Keep it stable with one logical idempotency identity.

Default1

Range1 <= value <= 9007199254740991

x-invoice-reference?string

Optional defensive copy of the request body's irn. When supplied it must match exactly.

Match^[A-Za-z0-9][A-Za-z0-9._:-]*$

Length1 <= length <= 200

X-Request-ID?string

Optional caller correlation metadata. Gateway creates a new authoritative request ID, returns it in the response X-Request-ID header and Problem Details requestId, and propagates that generated value to its dependencies.

Match^[A-Za-z0-9][A-Za-z0-9._:-]*$

Length1 <= length <= 128

Request Body

application/json

Send exactly the schema selected by the domain's approved mode. There is no mode field in the payload: PASSTHROUGH uses the regulator-owned snake_case document, while STORED uses Duplo's camelCase intake document and omits all server-owned routing fields.

TypeScript Definitions

Use the request body type in TypeScript.

irn*string

Match^[A-Za-z0-9][A-Za-z0-9._:-]*$

Length1 <= length <= 200

business_id*string

Match^(?!\s)(?!.*\s$)[^\\\u0000-\u001F\u007F]+$

Length1 <= length <= 255

accounting_supplier_party*

[key: string]?any

invoiceType*string

Value in"381" | "385" | "388" | "389"

invoiceNumber?string

Match^[A-Za-z0-9-]+$

Lengthlength <= 100

invoiceReferenceNumber*string

Durable IRN generated for this represented business.

Length1 <= length <= 100

billingReferences?array<>

Items1 <= items

billingReference?array<>Deprecated

Legacy alias for billingReferences.

Items1 <= items

issueDate*string

Invoice issue date; future dates are rejected.

Formatdate

taxPointDate?string

Formatdate

documentCurrency*string

Value in"NGN" | "USD" | "EUR" | "GBP" | "ZAR" | "KES"

taxCurrency*string

Value in"NGN" | "USD" | "EUR" | "GBP" | "ZAR" | "KES"

paymentStatus?string

Default"pending"

Value in"pending" | "paid" | "partially_paid" | "overdue"

paymentDate?string

Formatdate

supplierData*

customerId?string

Existing Dashboard invoice customer in the authenticated parent and test/live context. The customer must include the invoice module and invoice metadata with a postcode, otherwise intake is rejected. Customer creation is parent-scoped and does not receive gatewaySubBusinessId, so the same customer ID can be reused across represented businesses under that parent in the same state. A legacy customer with an existing non-null represented-business binding is accepted only for that matching gatewaySubBusinessId; the current customer API does not create or manage this legacy child scope. The invoice's represented-business identity comes only from the onboarding/list/detail gatewaySubBusinessId supplied in x-sub-business-id. Intake currently accepts omission, but customer data is operationally required for NRS readiness and no later Gateway edit attaches it; omit only if you intentionally accept later asynchronous rejection.

Formatuuid

payeeData?

taxRepresentativeData?

items*array<|>

Items1 <= items

discount?

notes?string

Length3 <= length <= 50

paymentTerms?string

Length3 <= length <= 50

paymentDetails?|

saveAsDraft?booleanDeprecated

Accepted by the shared DTO but ignored by STORED intake. STORED invoices are always accepted as submitted with pending NRS status; omit this field.

Defaultfalse

invoiceNumber?string

Match^[A-Za-z0-9-]+$

Lengthlength <= 100

invoiceReferenceNumber*string

Durable IRN generated for this represented business.

Length1 <= length <= 100

invoiceType*string

Stored invoice type. Credit notes (380) and debit notes (384) require at least one billingReferences or billingReference entry.

Value in"380" | "381" | "384" | "385" | "388" | "389"

billingReferences*array<>

Items1 <= items

billingReference?array<>Deprecated

Legacy alias for billingReferences.

Items1 <= items

issueDate*string

Invoice issue date; future dates are rejected.

Formatdate

taxPointDate?string

Formatdate

documentCurrency*string

Value in"NGN" | "USD" | "EUR" | "GBP" | "ZAR" | "KES"

taxCurrency*string

Value in"NGN" | "USD" | "EUR" | "GBP" | "ZAR" | "KES"

paymentStatus?string

Default"pending"

Value in"pending" | "paid" | "partially_paid" | "overdue"

paymentDate?string

Formatdate

supplierData*

customerId?string

Formatuuid

payeeData?

taxRepresentativeData?

items*array<|>

Items1 <= items

discount?

notes?string

Length3 <= length <= 50

paymentTerms?string

Length3 <= length <= 50

paymentDetails?|

saveAsDraft?booleanDeprecated

Accepted by the shared DTO but ignored by STORED intake. STORED invoices are always accepted as submitted with pending NRS status; omit this field.

Defaultfalse

invoiceNumber?string

Match^[A-Za-z0-9-]+$

Lengthlength <= 100

invoiceReferenceNumber*string

Durable IRN generated for this represented business.

Length1 <= length <= 100

invoiceType*string

Stored invoice type. Credit notes (380) and debit notes (384) require at least one billingReferences or billingReference entry.

Value in"380" | "381" | "384" | "385" | "388" | "389"

billingReferences?array<>

Items1 <= items

billingReference*array<>Deprecated

Legacy alias for billingReferences.

Items1 <= items

issueDate*string

Invoice issue date; future dates are rejected.

Formatdate

taxPointDate?string

Formatdate

documentCurrency*string

Value in"NGN" | "USD" | "EUR" | "GBP" | "ZAR" | "KES"

taxCurrency*string

Value in"NGN" | "USD" | "EUR" | "GBP" | "ZAR" | "KES"

paymentStatus?string

Default"pending"

Value in"pending" | "paid" | "partially_paid" | "overdue"

paymentDate?string

Formatdate

supplierData*

customerId?string

Formatuuid

payeeData?

taxRepresentativeData?

items*array<|>

Items1 <= items

discount?

notes?string

Length3 <= length <= 50

paymentTerms?string

Length3 <= length <= 50

paymentDetails?|

saveAsDraft?booleanDeprecated

Accepted by the shared DTO but ignored by STORED intake. STORED invoices are always accepted as submitted with pending NRS status; omit this field.

Defaultfalse

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/invoice/sign" \  -H "x-sub-business-id: string" \  -H "X-Request-ID: erp-run-20260916-0042" \  -H "Content-Type: application/json" \  -d '{    "business_id": "5be71d46-045d-4098-a466-4708afe7edac",    "irn": "INV000001-2A3A045D-20260818",    "issue_date": "2026-08-18",    "invoice_type_code": "381",    "accounting_supplier_party": {      "party_name": "Acme Retail Limited",      "tin": "12345678-0001"    }  }'

null

{
  "data": {
    "accepted": true,
    "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec"
  },
  "statusCode": 202,
  "message": "Invoice accepted for asynchronous signing",
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

Sign or Store NRS Invoice

Authorization

Header Parameters

Request Body

Response Body

200application/json

202application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

405application/problem+json

409application/problem+json

413application/problem+json

415application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

502application/problem+json

503application/problem+json

504application/problem+json

508application/problem+json

defaultapplication/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`