E-Invoice API Documentation
Complete guide to integrating FIRS e-invoice generation, validation, and management into your application.
Generate IRN
GETThis endpoint generates the Invoice Reference Number (IRN) using the invoice number, your provided FIRS service ID credential and a timestamp. The service ID is an 8-character string. Check your FIRS dashboard to get this.
Parameters
irn
string
The invoice reference number
Service ID Example
94ND90NRReturns
array['string'] - ['irn' => "INV001-XXXXXX-20151201"]
array:1 [
"irn" => "IPS23299943-XXXXXXXX-20251112"
]Get QR Code
GETQR Code is a base64 encoded image of your IRN and certificate. To successfully generate a QR Code, you must provide us with your public key and certificate, both available from your FIRS 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 FIRS 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 FIRS' 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",
"postal_zone": "23456",
"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",
"postal_zone": "23456",
"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 FIRS network to the customer and vendor.
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 FIRS HSN Codes that should be specified for each invoice item.
Parameters
No parameters required
Returns
Collection of HSN product codes
Get Service Codes
GETThis endpoint returns a collection of FIRS service codes that should be specified for each invoice item.
Parameters
No parameters required
Returns
Collection of FIRS service codes
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).