NRS MBS E-Invoice API
As an accredited Access Point Provider (APP) and System Integrator, Doftwerks provides this complete guide to integrating the Nigeria Revenue Service (NRS) Merchant Buyer Solution (MBS) e-invoice generation, validation, and management into your application.
Compliance Models
The NRS MBS framework introduces two implementation models depending on transaction type:
- Clearance Model (B2B / B2G): Real-time validation is required before issuance. Invoices must be submitted to the NRS platform for clearance to obtain an IRN and CSID prior to sending to the customer.
- Reporting Model (B2C): Transactions must be reported electronically to the NRS within 24 hours of issuance.
Generate IRN
GETThis endpoint performs validation on the NRS platform. It generates the Invoice Reference Number (IRN) alongside the Cryptographic Stamp Identifier (CSID) using the invoice number, your provided NRS service ID credential, and a timestamp. The service ID is an 8-character string found on your NRS dashboard.
Parameters
irn
string
The invoice reference number
Service ID Example
94ND90NRReturns
array['string'] - ['irn' => "INV001-XXXXXX-20151201", 'csid' => "base64String..."]
array:2 [
"irn" => "IPS23299943-XXXXXXXX-20251112",
"csid" => "eyJhbGciOiJSUzI1NiIsImsi..."
]Get QR Code
GETQR Code is a base64 encoded image encapsulating your IRN, CSID, and digital certificate. To successfully generate a QR Code, you must provide your public key and certificate, both available from your NRS dashboard.
Parameters
irn
string
The invoice reference number
size
integer
The QR code size in pixels
Returns
array['string'] - ['qr_code_png' => generatedCodeHere]
array:1 [
"qr_code_png" => "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEA..."
]Validate IRN
POSTThis endpoint validates the generated IRN. It takes the IRN as a string, validates it on the NRS network and returns an array of strings.
Parameters
irn
string
The invoice reference number to validate
Returns
array['string']
array:1 [
"ok" => true
]Validate Invoice
POSTThis endpoint validates the mapped invoice data and returns true or false.
Parameters
invoice_data
array['strings']
Complete invoice data object
Returns
array['string']
array:1 [
"ok" => true
]Sign Invoice
POSTThis endpoint signs the validated invoice data and returns true or false.
Parameters
invoice_data
array['strings']
Validated invoice data to be signed
Returns
array['string']
array:1 [
"ok" => true
]Download Invoice
GETThis endpoint is used to retrieve the NRS' recent invoice data as text. The text is then downloaded as a JSON file.
Parameters
irn
string
The invoice reference number
Returns
file (json)
{
"business_id": "5f350528-19f4-4185-9ee5-fff3f0284f97",
"irn": "INVIP0003-7A0819F4-20251101",
"issue_date": "2025-11-01",
"issue_time": "15:26:00",
"invoice_type_code": "381",
"document_currency_code": "NGN",
"tax_currency_code": "NGN",
"accounting_supplier_party": {
"party_name": "Vada Wilkinson",
"tin": "68452114-4234",
"email": "[email protected]",
"telephone": "+23456783434",
"business_description": "Retail",
"postal_address": {
"street_name": "201, MG Street",
"city_name": "Abuja",
"lga": "NG-FC-AMA",
"state": "NG-FC",
"postal_zone": "900211",
"country": "NG"
}
},
"billing_reference": null,
"payment_status": "PAID",
"reference": "",
"accounting_customer_party": {
"party_name": "Vada Wilkinson",
"tin": "68452114-4234",
"email": "[email protected]",
"telephone": "+23456777",
"business_description": "Retail",
"postal_address": {
"street_name": "",
"city_name": "Abuja",
"lga": "NG-FC-AMA",
"state": "NG-FC",
"postal_zone": "900211",
"country": "NG"
}
},
"payment_means": null,
"allowance_charge": null,
"tax_total": [
{
"tax_amount": 900,
"tax_subtotal": [
{
"taxable_amount": 12000,
"tax_amount": 900,
"tax_category": {
"id": "STANDARD_VAT",
"percent": 7.5
}
}
]
}
],
"legal_monetary_total": {
"line_extension_amount": 12000,
"tax_exclusive_amount": 12000,
"tax_inclusive_amount": 12900,
"payable_amount": 12900
},
"invoice_line": [
{
"hsn_code": "8502.40",
"product_category": "Electronics",
"invoiced_quantity": 10,
"line_extension_amount": 2000,
"item": {
"name": "Samsung Type C to 3.5 convertor",
"description": "USB C to audio convertor",
"sellers_item_identification": "SKU-001"
},
"price": {
"price_amount": 200,
"base_quantity": 10,
"price_unit": "NGN per 1"
},
"discount_amount": 0,
"discount_rate": 0,
"fee_rate": 0,
"fee_amount": 0,
"tax_code": "",
"tax_rate": 0
},
{
"hsn_code": "8502.40",
"product_category": "Electronics",
"invoiced_quantity": 5,
"line_extension_amount": 10000,
"item": {
"name": "Monndrop Chu IEMs",
"description": "Wired IEM",
"sellers_item_identification": "SKU-002"
},
"price": {
"price_amount": 2000,
"base_quantity": 5,
"price_unit": "NGN per 1"
},
"discount_amount": 0,
"discount_rate": 0,
"fee_rate": 0,
"fee_amount": 0,
"tax_code": "",
"tax_rate": 0
}
],
"sale_type": 0
}Confirm Invoice
GETThis endpoint checks the invoice details of an IRN and confirms its transmission and delivery status.
Parameters
irn
string
The invoice reference number
Returns
array['strings']
array:6 [
"issue_date" => "2025-11-03"
"due_date" => "2025-11-03"
"sync_date" => "2025-11-03"
"payment_status" => "PAID"
"transmitted" => true
"delivered" => false
]Transmit Invoice
POSTThis endpoint is used to transmit the generated invoice data through the NRS network to fulfill the clearance (B2B/B2G) or reporting (B2C) mandates.
Parameters
invoice_data
array['strings']
Complete invoice data to transmit
Returns
array['strings']
array:1 [
"ok" => true
]Get Product Codes
GETThis endpoint returns a collection of NRS HSN Codes that should be specified for each invoice item.
Parameters
No parameters required
Returns
Collection of NRS HSN product codes
[
{
"hsn_code": "8502.40",
"description": "Electric rotary converters",
"product_category": "Electronics"
}
]Get Service Codes
GETThis endpoint returns a collection of NRS service codes that should be specified for each invoice item.
Parameters
No parameters required
Returns
Collection of NRS service codes
[
{
"service_code": "SVC-001",
"description": "Consulting Services",
"rate": 7.5
}
]Get State Codes
GETThis endpoint returns a collection of NRS State codes required for specifying the `state` field in postal addresses.
Parameters
No parameters required
Returns
Collection of NRS State codes
[
{
"state_code": "NG-FC",
"name": "Federal Capital Territory"
},
{
"state_code": "NG-AB",
"name": "Abia State"
}
]Get LGA Codes
GETThis endpoint returns a collection of NRS Local Government Area (LGA) codes mapping to a respective state, used for specifying the `lga` field in postal addresses.
Parameters
No parameters required. Optional `?state_code=NG-FC` URL query to filter by State.
Returns
Collection of NRS LGA codes
[
{
"lga_code": "NG-FC-AMA",
"name": "Abuja Municipal Area Council",
"state_code": "NG-FC"
},
{
"lga_code": "NG-AB-ANO",
"name": "Aba North",
"state_code": "NG-AB"
}
]We are committed to providing a reliable and high-performance service. For detailed information on service availability, performance metrics, and support commitments, please review our E-Invoice Service Level Agreement (SLA).