NRS E-Invoicing

Overview

Yona serves as both a System Integrator (SI) and an Access Point Provider (APP) for Nigeria’s e-invoicing mandate under the Federal Inland Revenue Service (FIRS), operating through the Nigeria Revenue Service (NRS) platform.

As a System Integrator, Yona standardizes invoice data from your systems into the NRS-compliant format, validates fields, and computes tax totals. As an Access Point Provider, Yona generates Invoice Reference Numbers (IRNs), digitally signs invoices, transmits them to the NRS, and routes status updates back to your application.

Through Yona’s API, businesses can create, sign, and submit invoices to the NRS without building a direct integration. Yona handles:

• Invoice Reference Number (IRN) generation
• Digital signing (ECDSA or RSA)
• Payload transformation to NRS-compliant format
• Transmission to and routing from the NRS
• Status tracking via webhooks
• PDF generation with embedded QR code and IRN for NRS compliance

How it works

1. Register your seller and buyer. Each must have a valid TIN, email, and postal address. Sellers require a verified TIN for submission. Use the tax ID lookup endpoint to verify TINs before submission.
2. Create a draft invoice. Provide seller, buyer, line items with HSN codes, quantities, unit prices, and tax rates. Yona auto-calculates line totals, tax amounts, and monetary totals. Status: draft.
3. Finalise the invoice. Lock the draft to freeze totals and prepare it for submission. Status: finalised. This does not require an NRS connection.
4. Submit the invoice. Requires an active NRS connection (status: CONNECTED). Yona validates against NRS requirements, generates an IRN, and queues for processing. Status: queued.
5. Yona processes the submission. The invoice is transformed to the NRS payload format, digitally signed, and transmitted to the NRS. Status: pending.
6. NRS responds. The tax authority validates and accepts or rejects the invoice. Yona updates the invoice status and dispatches a webhook event to your endpoint (invoice.approved, invoice.rejected, or invoice.submission_failed).
7. Download or query. Once accepted, download the invoice as PDF (which includes the NRS QR code and IRN) or query real-time status from the tax authority.

Cancellation

You cannot delete or modify an invoice after NRS acceptance. To void an accepted invoice, call POST /i/v1/invoices/:id/cancel. Yona automatically creates a credit note (NRS code 381) on your behalf. This is the only NRS-compliant path for voiding accepted invoices.

Rendered invoice example

The image below shows a sample human-readable tax invoice generated by the platform after a successful submission. The Tax Information section at the bottom contains the IRN and the QR code returned by the API. Both must appear on every printed invoice for NRS compliance and verifiability.

QR code

After a successful submission, the NRS returns a QR code for the invoice. This QR code is:

• Embedded in the generated PDF
• Required on every printed invoice for NRS compliance and verifiability

The QR code allows anyone to scan and verify the invoice’s authenticity against the NRS.

Invoice Reference Number (IRN)

Format: {invoiceNumber}-{serviceId}-{dateStr}

Example: INV001-94ND90NR-20240611

The Service ID is assigned by NRS when your organization connects to the tax authority. Yona generates the IRN automatically at submission time.

NRS payload structure

When you submit an invoice, Yona automatically maps your seller, buyer, and line item data to the NRS-compliant format. Understanding what the NRS requires helps you provide the right data upfront.

Supplier party (mandatory)

Yona maps this from your registered seller.

Customer party

Same structure as supplier. Yona maps this from your registered buyer. Buyer TIN is optional (consumers may not have one).

Line items (mandatory, minimum 1)

Each line item requires either an HS code (for goods) or an ISIC code (for services).

Goods classification

Service classification (alternative)

Item and pricing fields

For supported unit codes and HSN codes, see Invoices API.

Invoice type codes

Invoice kinds

The NRS classifies invoices by transaction type: B2B (business-to-business), B2C (business-to-consumer), or B2G (business-to-government). This affects validation rules. For example, B2C invoices do not require a buyer TIN. Yona determines the kind automatically based on the buyer’s party type.

Tax categories

NRS supports additional tax categories including WITHHOLDING_TAX, SERVICE_TAX, STAMP_DUTY, IMPORT_DUTY, EXPORT_DUTY, and others. Use GET /i/v1/invoices/resources/tax-categories to retrieve the full list. Yona passes any valid tax category code through to the authority.

Monetary totals (mandatory)

All auto-calculated from line items:

Digital signing and security

Invoice signing

Every invoice is digitally signed before transmission to the NRS:

• Algorithm: ECDSA (default) or RSA, configurable per environment
• Curve: prime256v1 (ECDSA default)
• Output: A Cryptographic Stamp ID (CSID) stored in regulatoryData.cryptographicStamp
• Non-repudiation: The CSID proves the invoice was submitted by an authorized integrator and has not been tampered with

Webhook events

Yona dispatches webhook events as invoices move through submission. Events are filtered by API mode: sandbox invoices only trigger webhooks on sandbox endpoints.

NRS status mapping

The NRS sends status updates to Yona, which are mapped to invoice statuses:

TRANSMITTING and TRANSMITTED are progress signals only. The invoice stays in pending until the recipient explicitly acknowledges it (ACKNOWLEDGED) or the transmission fails (FAILED).

See Webhooks for setup and payload details.

API endpoints

Base path: https://gateway.useyona.com/i/v1/invoices

Invoice lifecycle

Status and download

Tax authority and reference data

For full request/response documentation, see Invoices API.

Example: create and submit an invoice

1. Create a draft invoice

POST /i/v1/invoices

curl -X POST https://gateway.useyona.com/i/v1/invoices \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerId": "c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e",
    "buyerId": "d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f",
    "invoiceNumber": "INV-2026-001",
    "invoiceDate": "2026-04-30",
    "dueDate": "2026-05-30",
    "currency": "NGN",
    "lineItems": [
      {
        "description": "Bags of premium rice",
        "hsnCode": "1006.30",
        "productCategory": "Cereals; rice, semi-milled or wholly milled, whether or not polished or glazed",
        "quantity": 15,
        "unitCode": "XBG",
        "unitPrice": 45000,
        "taxPercent": 7.5
      },
      {
        "description": "IT consulting services",
        "isicCode": "6201",
        "serviceCategory": "Computer programming activities",
        "quantity": 40,
        "unitCode": "HUR",
        "unitPrice": 15000,
        "taxPercent": 7.5
      }
    ],
    "paymentTerms": "Net 30"
  }'

2. Finalise the invoice

POST /i/v1/invoices/:id/finalise

No request body. Locks the invoice and freezes totals. Returns the full invoice with status: "finalised".

curl -X POST https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/finalise \
  -H "Authorization: Bearer sk_test_your_key_here"

3. Submit to the tax authority

POST /i/v1/invoices/:id/submit

No request body. Requires an active NRS connection.

curl -X POST https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/submit \
  -H "Authorization: Bearer sk_test_your_key_here"

NRS payload (generated by Yona at submission)

When Yona processes the submission, it transforms your invoice into the following NRS-compliant format and sends it to POST /api/v1/invoice/sign:

Related pages

• Invoice Lifecycle for the full status diagram, transitions, and retry behavior
• Credits and Billing for credit costs per operation and balance management
• Invoices API for endpoints, supported unit codes, and HSN code search
• Sellers
• Buyers