WiseWage NRS e-Invoicing integration

This reference documents the current WiseWage B2B commercial-invoice implementation against NRS v1.1. Draft creation is internal; the external operation documented by NRS is invoice validation. The examples contain fictional identities and cannot be submitted as enabled taxpayers.

Create Invoice: authenticated WiseWage draft request

POST /api/admin/management-accounting/e-invoicing with action: createDraft. Requires a signed-in, authorised Management Accounts user and company/entity access; this is not an API-key-based public customer endpoint. Select an open period and configured accounts. The seller comes from the saved NRS business profile; the server assigns the permanent invoice number and IRN and calculates amounts.

The scope identifiers, customer, issue date, buyer fiscal details, account mappings and at least one line are required. Company Code and Cost Center follow the managed business classification rules; Output VAT is required for taxable lines. Due date, buyer reference, narration, business description and seller item reference are optional. This example includes all fields accepted by the draft form.

{
  "action": "createDraft",
  "companyId": "<authorised-company-id>",
  "entityId": "<managed-business-id>",
  "periodId": "<open-period-id>",
  "draft": {
    "customerId": "<active-customer-id>",
    "issueDate": "2026-09-06",
    "dueDate": "2026-10-06",
    "currency": "NGN",
    "paymentMeansCode": "30",
    "buyerReference": "PO-DEMO-2026-0001",
    "narration": "Fictional sample",
    "companyCode": "<configured-company-code>",
    "costCenterCode": "<eligible-cost-center>",
    "revenueAccountCode": "<revenue-account>",
    "receivableAccountCode": "<receivable-account>",
    "outputVatAccountCode": "<output-vat-account>",
    "buyer": {
      "taxId": "10000002-0001",
      "email": "accounts@meridian-trade.example",
      "telephone": "+2348020000002",
      "businessDescription": "Fictional wholesale and distribution business",
      "streetName": "25 Demonstration Commerce Road",
      "cityName": "Lagos",
      "postalZone": "101233",
      "lgaCode": "NG-LA-LMA",
      "stateCode": "NG-LA",
      "countryCode": "NG"
    },
    "lines": [
      {
        "entryMode": "QUANTITY",
        "description": "Software integration service",
        "quantity": 2,
        "unitPrice": 150000,
        "unitCode": "EA",
        "itemType": "SERVICE",
        "classificationCode": "6201",
        "classificationName": "Computer programming activities",
        "sellerItemReference": "SVC-DEMO-001",
        "taxCategoryCode": "STANDARD_VAT"
      }
    ]
  }
}

NRS invoice validation request

POST {NRS_API_BASE_URL}/api/v1/invoice/validate. Use the API origin and credentials issued for the selected environment, not the documentation website. Authentication is server-side using the two headers below. Never expose credentials in browser code or submission documents.

curl --request POST "$NRS_API_BASE_URL/api/v1/invoice/validate" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "x-api-key: <NRS_API_KEY>" \
  --header "x-api-secret: <NRS_API_SECRET>" \
  --data-binary @invoice.json

Save the complete example below as invoice.json. Replace fictional identities with authorised sandbox fixtures before a sandbox submission.

{
  "business_id": "9f36d708-4c91-4e2a-92c8-7a75f418b603",
  "irn": "INV00000001-A1B2C3D4-20260906",
  "issue_date": "2026-09-06",
  "due_date": "2026-10-06",
  "invoice_type_code": "381",
  "invoice_kind": "B2B",
  "payment_status": "PENDING",
  "note": "Fictional sample prepared solely for NRS system-integration review.",
  "tax_point_date": "2026-09-06",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  "buyer_reference": "PO-DEMO-2026-0001",
  "order_reference": "PO-DEMO-2026-0001",
  "accounting_supplier_party": {
    "party_name": "Acacia Systems Nigeria Limited",
    "tin": "10000001-0001",
    "email": "billing@acacia-systems.example",
    "telephone": "+2348010000001",
    "business_description": "Business software implementation and support services",
    "postal_address": {
      "street_name": "10 Sample Technology Avenue",
      "city_name": "Ikeja",
      "postal_zone": "100001",
      "lga": "NG-LA-IKE",
      "state": "NG-LA",
      "country": "NG"
    }
  },
  "accounting_customer_party": {
    "party_name": "Meridian Trade Services Limited",
    "tin": "10000002-0001",
    "email": "accounts@meridian-trade.example",
    "telephone": "+2348020000002",
    "business_description": "Fictional wholesale and distribution business",
    "postal_address": {
      "street_name": "25 Demonstration Commerce Road",
      "city_name": "Lagos",
      "postal_zone": "101233",
      "lga": "NG-LA-LMA",
      "state": "NG-LA",
      "country": "NG"
    }
  },
  "payment_means": [
    {
      "payment_means_code": "30",
      "payment_due_date": "2026-10-06"
    }
  ],
  "tax_total": [
    {
      "tax_amount": 22500,
      "tax_subtotal": [
        {
          "taxable_amount": 300000,
          "tax_amount": 22500,
          "tax_category": {
            "id": "STANDARD_VAT",
            "percent": 7.5
          }
        }
      ]
    }
  ],
  "legal_monetary_total": {
    "line_extension_amount": 300000,
    "tax_exclusive_amount": 300000,
    "tax_inclusive_amount": 322500,
    "payable_amount": 322500
  },
  "invoice_line": [
    {
      "isic_code": "6201",
      "service_category": "Computer programming activities",
      "invoiced_quantity": 2,
      "line_extension_amount": 300000,
      "item": {
        "name": "Configuration and integration of a fictional business software environment",
        "description": "Configuration and integration of a fictional business software environment",
        "sellers_item_identification": "SVC-DEMO-001"
      },
      "price": {
        "price_amount": 150000,
        "base_quantity": 1,
        "price_unit": "EA"
      }
    }
  ]
}

Supported request fields, including nested structures

Requiredness below describes WiseWage's B2B payload, which requires buyer details. Optional parent objects may be omitted; their required children apply when supplied. Goods use HSN/product category; services use ISIC/service category. Monetary values are JSON numbers, rounded to two decimal places. Line totals, VAT subtotals and payable totals must reconcile.

Download the supported request JSON Schema. This documents WiseWage's supported subset, not every optional NRS feature. B2C, cross-border invoices, discounts, fees, third-party parties and extra document references are outside this release.

Responses and correction workflow

NRS documents a success body such as the example below. It is illustrative documentation, not evidence of an actual sandbox submission. WiseWage retains the received HTTP status and sanitised response for each attempt.

{
  "status": true,
  "message": "success"
}

Illustrative WiseWage validation error (HTTP 400; not an NRS response):

{
  "error": "Business description must not exceed 255 characters.",
  "code": "INVALID_REQUEST"
}

HTTP 400: correct the identified invoice fields. HTTP 401/403: check credentials, permissions and taxpayer association. Timeouts: retain the attempt and retry through the same invoice workflow. Do not renumber an invoice to retry. Validation is separate from approval and reporting.

IRN and encrypted verification QR

The IRN joins an alphanumeric invoice number, the taxpayer's eight-character Service ID and YYYYMMDD issue date with hyphens. For the QR payload, append a period and UNIX timestamp to that IRN, include the issued certificate, encrypt the JSON with the downloaded RSA public key using the documented OpenSSL-compatible padding, then encode the ciphertext as Base64. The QR contains that Base64 ciphertext, never a plain IRN or invented verification URL.

Administrators configure the matching NRS public key and certificate server-side before fiscalization. Missing or invalid keys block the reporting request. Historical invoices without encrypted QR evidence remain downloadable with a warning; they must not be resubmitted merely to replace a QR code.

Linked credit notes (380) and debit notes (384) use billing_reference to identify the original fiscalized invoice. Create them from the original invoice with a reason and selected line amounts; inherited VAT and account mappings are retained. They require validation, approval and confirmation. Fiscalized cancellation is unavailable pending confirmation of the supported NRS process. Reconciliation compares saved NRS evidence, register values and current ledger receivable, revenue and output VAT amounts; it does not verify filed VAT returns.

Download fictional QR format evidence (encrypted payload, test public key and test certificate; no private key).

The downloadable sample demonstrates the encrypted format using locally generated test keys. It is explicitly not NRS-verified, not a sandbox acceptance record and not valid for tax use. Real verification requires the NRS-issued cryptographic materials and an MBS360/NRS verification check.

Official v1.1 references: Invoice Schema, Generate IRN, QR Code.