Nigeria E-Invoicing API Documentation
Introduction
Nigeria's Federal Inland Revenue Service (FIRS) is advancing its tax administration by implementing an electronic invoicing (e-invoicing) system. This initiative aims to enhance tax compliance, increase transparency, and reduce revenue losses, thereby improving the country's tax-to-GDP ratio.
Key Developments in Nigeria's E-Invoicing System:
-
Pilot Phase Initiation: In February 2025, FIRS launched a pilot phase of the e-invoicing system, targeting large taxpayers across various sectors. This phase is designed to gather insights and address potential challenges before a full-scale rollout.
-
Full Implementation Timeline: Based on the outcomes of the pilot, FIRS plans to fully implement the e-invoicing system by July 2025, encompassing Business-to-Business (B2B), Business-to-Consumer (B2C), and Business-to-Government (B2G) transactions.
-
System Features: The e-invoicing platform, known as the Merchant Buyer Solution (MBS), is designed to replace traditional paper-based invoicing with a digital framework that facilitates real-time validation and storage of transactions.
Technical Compliance:
To comply with the new regulations, businesses must use authorized e-invoicing solutions that integrate with the FIRS platform. The system offers two main options:
- Direct Issuance: Businesses can generate invoices directly through the FIRS e-invoice portal.
- System Integration: Companies can integrate their existing invoicing software with the FIRS e-invoice system via API.
Authentication
All API requests require authentication headers. The following headers must be included in every request:
Base URL
All API endpoints use the following base URL:
https://cryptware-einvoicing.flick.network
Required Headers
- Name
participant-id- Type
- string
- Description
Unique identifier for the registered participant/supplier.
- Name
x-api-key- Type
- string
- Description
API key for authentication. Contact your administrator to obtain this key.
- Name
Content-Type- Type
- string
- Description
Set to
application/jsonfor POST/PATCH requests.
Common Data Structures
These data structures are reusable components used across various API endpoints. Understanding these structures is essential for proper API integration.
Invoice Document
The main invoice document structure containing all invoice details.
- Name
document_identifier- Type
- string
- Description
Unique identifier for the invoice document. This is your internal reference number. (Mandatory)
- Name
issue_date- Type
- string (YYYY-MM-DD)
- Description
Date when the invoice was issued. (Mandatory)
- Name
due_date- Type
- string (YYYY-MM-DD)
- Description
Payment due date for the invoice. (Optional)
- Name
invoice_type_code- Type
- string
- Description
Code representing the type of invoice (e.g., "380" for commercial invoice, "384" for corrected invoice). (Mandatory)
- Name
document_currency_code- Type
- string
- Description
Currency code for the invoice (e.g., "NGN" for Nigerian Naira). (Mandatory)
- Name
tax_currency_code- Type
- string
- Description
Currency code for tax calculations (e.g., "NGN"). (Mandatory)
- Name
payment_status- Type
- string
- Description
Current payment status: "PENDING", "PAID", or "REJECTED". Defaults to "PENDING". (Optional)
- Name
business_model- Type
- string
- Description
Business transaction model: "B2B" (Business-to-Business), "B2C" (Business-to-Consumer), or "B2G" (Business-to-Government). (Optional)
Accounting Customer Party
This structure contains comprehensive information about the customer (buyer) to whom the invoice is being issued. This is a mandatory component of every invoice.
- Name
party_name- Type
- string
- Description
The legal or registered name of the customer. (Mandatory)
- Name
tin- Type
- string
- Description
Tax Identification Number (TIN) of the customer. Must be registered with FIRS. (Mandatory)
- Name
email- Type
- string
- Description
Email address of the customer for invoice delivery and notifications. (Mandatory)
- Name
telephone- Type
- string
- Description
Phone number of the customer. Must include country code starting with
+(e.g., "+234" for Nigeria). (Optional)
- Name
business_description- Type
- string
- Description
Brief description of the customer's business activity or industry sector. (Optional)
- Name
postal_address- Type
- object
- Description
Physical address of the customer. (Mandatory)
- Name
street_name- Type
- string
- Description
Street address including building number and street name.
- Name
city_name- Type
- string
- Description
City or town name.
- Name
postal_zone- Type
- string
- Description
Postal code or zip code.
- Name
state- Type
- string
- Description
State code (e.g., "NG-LA" for Lagos). (Optional)
- Name
country- Type
- string
- Description
Country code (ISO 3166-1 alpha-2), e.g., "NG" for Nigeria. (Mandatory)
Invoice Line Items
Invoice line items represent individual products or services included in an invoice. Each invoice must contain at least one line item. This array structure allows multiple items to be included in a single invoice.
- Name
hsn_code- Type
- string
- Description
Harmonized System Nomenclature (HSN) code for product classification. This is a globally standardized system for classifying traded products. (Mandatory)
- Name
product_category- Type
- string
- Description
Category or classification of the product/service (e.g., "Lubricants", "Food and Beverages", "Electrical energy"). (Mandatory)
- Name
item_name- Type
- string
- Description
Descriptive name of the product or service. (Mandatory)
- Name
sellers_item_identification- Type
- string
- Description
Seller's internal SKU or product identification code. (Optional)
- Name
invoiced_quantity- Type
- number
- Description
Quantity of items being invoiced. (Mandatory)
- Name
uom- Type
- string
- Description
Unit of measurement (e.g., "ST" for stock, "PC" for pieces, "KG" for kilograms, "LTR" for liters). (Mandatory)
- Name
price_amount- Type
- number
- Description
Unit price per item before discounts and taxes. (Mandatory)
- Name
discount_rate- Type
- number
- Description
Discount rate as a percentage (e.g., 10.5 for 10.5% discount). (Optional)
- Name
discount_amount- Type
- number
- Description
Fixed discount amount in the document currency. (Optional)
- Name
fee_rate- Type
- number
- Description
Additional fee rate as a percentage. (Optional)
- Name
fee_amount- Type
- number
- Description
Fixed fee amount in the document currency. (Optional)
- Name
line_extension_amount- Type
- number
- Description
Total amount for this line item before taxes (calculated as: quantity × price - discount + fee). (Optional - can be auto-calculated)
- Name
tax_rate- Type
- number
- Description
Applicable tax rate as a percentage (e.g., 7.5 for 7.5% VAT). (Mandatory)
- Name
tax_category_id- Type
- string
- Description
Tax category identifier (e.g., "ZERO_VAT", "LOCAL_SALES_TAX", "STANDARD_VAT", "EXEMPT_VAT"). Use the
/resources/tax-categoriesendpoint to get valid values. (Mandatory)
Important: The hsn_code, uom, and tax_category_id fields should use values from the respective resource endpoints to ensure compliance with FIRS standards.
Postal Address
Standard address structure used in various API requests.
- Name
street_name- Type
- string
- Description
Street address including building/house number and street name. (Mandatory)
- Name
city_name- Type
- string
- Description
City or town name. (Mandatory)
- Name
postal_zone- Type
- string
- Description
Postal code or zip code. (Mandatory)
- Name
state- Type
- string
- Description
State or region code (e.g., "NG-LA" for Lagos). (Optional)
- Name
country- Type
- string
- Description
Country code using ISO 3166-1 alpha-2 format (e.g., "NG" for Nigeria). (Mandatory)
Invoice APIs
Search Invoices
Retrieve a list of invoices based on search criteria. This endpoint allows you to query and filter invoices.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/invoice/search \
--header 'participant-id: 019b4e74-d285-72d6-b23a-005c40328079' \
--header 'x-api-key: 72aa34346860bfb721f081b8b96cf48adecc0dda00e76f2cb16882b05bbeca7b'
Response
{
"status": "success",
"data": {
"invoices": [
{
"irn": "TSTCRPT-1554544516-C1B44E6C-20250305",
"document_identifier": "TSTCRPT-1554544516",
"issue_date": "2025-03-05",
"status": "SIGNED",
"total_amount": 150.00
}
],
"total": 1
}
}
Download Invoice Details
Download complete invoice details by Invoice Reference Number (IRN). This endpoint returns the full invoice document.
Path Parameters
- Name
irn- Type
- string
- Description
Invoice Reference Number (e.g., "TSTCRPT-1554544516-C1B44E6C-20250305").
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/invoice/download/TSTCRPT-1554544516-C1B44E6C-20250305 \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": {
"irn": "TSTCRPT-1554544516-C1B44E6C-20250305",
"document_identifier": "TSTCRPT-1554544516",
"issue_date": "2025-03-05",
"invoice_type_code": "380",
"document_currency_code": "NGN",
"accounting_customer_party": {
"party_name": "cryptware",
"tin": "23773131-0001",
"email": "crypt@g.com"
},
"invoice_line": [],
"pdf_url": "https://example.com/invoice.pdf"
}
}
Get Invoice Details with QR
Retrieve invoice details including QR code information. This endpoint is useful for displaying invoices with embedded QR codes for verification.
Path Parameters
- Name
irn- Type
- string
- Description
Invoice Reference Number.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/invoice/details/TSTCRPT-2555574445-C1B44E6C-20250305 \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": {
"irn": "TSTCRPT-2555574445-C1B44E6C-20250305",
"qr_code": "iVBORw0KGgoAAAANSUhEUgAA...",
"qr_code_url": "https://example.com/qr/TSTCRPT-2555574445-C1B44E6C-20250305",
"invoice_details": {
"document_identifier": "TSTCRPT-2555574445",
"issue_date": "2025-03-05",
"total_amount": 100.50
}
}
}
Generate Invoice
Generate a new e-invoice and submit it to the FIRS platform. This is the primary endpoint for creating invoices.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
- Name
Content-Type- Type
- string
- Description
Must be
application/json.
Request Body
- Name
document_identifier- Type
- string
- Description
Unique document reference number or identifier.
- Name
issue_date- Type
- string
- Description
Date on which the invoice was issued (format: YYYY-MM-DD).
- Name
invoice_type_code- Type
- string
- Description
Code representing the invoice type (e.g., "380" for commercial invoice, "384" for corrected invoice).
- Name
document_currency_code- Type
- string
- Description
Currency code for the invoice (e.g., "NGN").
- Name
tax_currency_code- Type
- string
- Description
Currency code for tax calculations (e.g., "NGN").
- Name
payment_status- Type
- string
- Description
Payment status (e.g., "PENDING", "PAID", "REJECTED"). Optional, defaults to "PENDING".
- Name
accounting_customer_party- Type
- object
- Description
Customer/buyer information. See Common Data Structures section.
- Name
invoice_line- Type
- array
- Description
Array of invoice line items. See Common Data Structures section. At least one item required.
Request
curl --request POST \
--url {{baseUrl}}/invoice/generate \
--header 'Content-Type: application/json' \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}' \
--data '{
"document_identifier": "TSTCRPT-1554544515",
"issue_date": "2025-03-05",
"invoice_type_code": "380",
"document_currency_code": "NGN",
"tax_currency_code": "NGN",
"accounting_customer_party": {
"party_name": "cryptware",
"email": "crypt@g.com",
"tin": "23773131-0001",
"telephone": "+234",
"business_description": "Lubricants",
"postal_address": {
"street_name": "4 POINT ROAD OLUYOLA ESTATE",
"city_name": "IBADAN",
"postal_zone": "OLUYOLE",
"country": "NG"
}
},
"invoice_line": [
{
"hsn_code": "2710.19",
"price_amount": 10,
"discount_amount": 1,
"uom": "ST",
"invoiced_quantity": 2.23,
"product_category": "Lubricants",
"tax_rate": 0,
"tax_category_id": "ZERO_VAT",
"item_name": "QUARTZ 5000 SL 20W50 205L TOT NG",
"sellers_item_identification": "209897"
},
{
"hsn_code": "2710.19",
"price_amount": 10,
"discount_amount": 2,
"uom": "ST",
"invoiced_quantity": 7.25,
"product_category": "Lubricants",
"tax_rate": 0,
"tax_category_id": "ZERO_VAT",
"item_name": "RUBIA TIR 7400 15W40 205L TOT NG",
"sellers_item_identification": "189402"
}
]
}'
Response
{
"status": "success",
"message": "Invoice generated successfully",
"data": {
"irn": "TSTCRPT-1554544515-C1B44E6C-20250305",
"status": "SIGNED",
"qr_code": "XtIv69xI4CDxAqrvPL+8c/JhHmwWxfOqo+IyTwHBZCf...",
"firs_response": {
"code": 201,
"message": "Invoice accepted"
},
"steps_completed": [
"irn_validation",
"invoice_validation",
"invoice_signing",
"database_storage"
]
}
}
Error Response
{
"status": "error",
"message": "Validation failed",
"errors": [
{
"field": "document_identifier",
"message": "Document identifier is required"
}
]
}
Update Invoice Payment Status
Update the payment status of an existing invoice. This endpoint allows you to mark invoices as paid, rejected, or update payment references.
Path Parameters
- Name
irn- Type
- string
- Description
Invoice Reference Number.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
- Name
Content-Type- Type
- string
- Description
Must be
application/json.
Request Body
- Name
payment_status- Type
- string
- Description
New payment status. Accepted values: "PAID", "PENDING", "REJECTED".
- Name
reference- Type
- string
- Description
Payment reference or transaction ID (optional).
Request
curl --request PATCH \
--url {{baseUrl}}/invoice/TSTCRPT-2555574445-C1B44E6C-20250305 \
--header 'Content-Type: application/json' \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}' \
--data '{
"payment_status": "REJECTED",
"reference": "ref-125669"
}'
Response
{
"status": "success",
"message": "Invoice payment status updated successfully",
"data": {
"irn": "TSTCRPT-2555574445-C1B44E6C-20250305",
"payment_status": "REJECTED",
"reference": "ref-125669",
"updated_at": "2025-03-05T14:30:00Z"
}
}
Resource APIs
Resource APIs provide access to reference data and master data required for invoice generation, such as tax categories, HSN codes, currencies, and more.
Get All Resources
Retrieve all available resource types in a single request. This is a convenient endpoint to fetch all master data at once.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/resources/all \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": {
"hs_codes": [],
"service_codes": [],
"currencies": [],
"countries": [],
"invoice_types": [],
"payment_means": [],
"tax_categories": [],
"vat_exemptions": []
}
}
Get HSN Codes
Retrieve the list of Harmonized System Nomenclature (HSN) codes. These codes classify products for tax purposes.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/resources/hs-codes \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": [
{
"code": "2710.19",
"description": "Petroleum oils and oils obtained from bituminous minerals"
},
{
"code": "271600",
"description": "Electrical energy"
}
]
}
Get Service Codes
Retrieve the list of service classification codes for service-based invoices.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/resources/services-codes \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": [
{
"code": "SRV001",
"description": "Consulting Services"
},
{
"code": "SRV002",
"description": "IT Services"
}
]
}
Get Currencies
Retrieve the list of supported currency codes for invoicing.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/resources/currencies \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": [
{
"code": "NGN",
"name": "Nigerian Naira",
"symbol": "₦"
},
{
"code": "USD",
"name": "United States Dollar",
"symbol": "$"
}
]
}
Get Countries
Retrieve the list of country codes (ISO 3166-1 alpha-2) supported by the system.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/resources/countries \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": [
{
"code": "NG",
"name": "Nigeria"
},
{
"code": "US",
"name": "United States"
}
]
}
Get Invoice Types
Retrieve the list of invoice type codes and their descriptions. These codes define the nature of the invoice (e.g., commercial invoice, credit note).
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/resources/invoice-types \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": [
{
"code": "380",
"description": "Commercial Invoice"
},
{
"code": "384",
"description": "Corrected Invoice"
},
{
"code": "396",
"description": "Credit Note"
}
]
}
Get Payment Means
Retrieve the list of payment method codes (e.g., bank transfer, cash, card).
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/resources/payment-means \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": [
{
"code": "10",
"description": "Cash"
},
{
"code": "30",
"description": "Credit Transfer"
},
{
"code": "48",
"description": "Bank Card"
}
]
}
Get Tax Categories
Retrieve the list of tax category codes used for invoice line items.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/resources/tax-categories \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": [
{
"id": "ZERO_VAT",
"description": "Zero-rated VAT",
"rate": 0.0
},
{
"id": "LOCAL_SALES_TAX",
"description": "Local Sales Tax",
"rate": 7.5
},
{
"id": "STANDARD_VAT",
"description": "Standard VAT",
"rate": 7.5
}
]
}
Get VAT Exemptions
Retrieve the list of VAT exemption reasons and codes.
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/resources/vat-exemptions \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": [
{
"code": "VATEX-NG-001",
"description": "Export of goods outside Nigeria"
},
{
"code": "VATEX-NG-002",
"description": "Goods and services to diplomats"
}
]
}
Transmitting APIs
Transmit Lookup
Look up the transmission status of an invoice by its identifier. This endpoint helps track whether an invoice has been successfully transmitted to FIRS.
Path Parameters
- Name
id- Type
- string
- Description
Invoice identifier or document reference number (e.g., "5524270296-A2EC78CC-20251203").
Headers
- Name
participant-id- Type
- string
- Description
Your registered participant ID.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication.
Request
curl --request GET \
--url {{baseUrl}}/transmitting/lookup/5524270296-A2EC78CC-20251203 \
--header 'participant-id: {{participant-id}}' \
--header 'x-api-key: {{x-api-key}}'
Response
{
"status": "success",
"data": {
"id": "5524270296-A2EC78CC-20251203",
"transmission_status": "TRANSMITTED",
"transmitted_at": "2025-12-03T10:30:00Z",
"firs_acknowledgment": {
"status": "ACCEPTED",
"timestamp": "2025-12-03T10:30:05Z"
}
}
}
Error Response
{
"status": "error",
"message": "Invoice not found",
"error_code": "INVOICE_NOT_FOUND"
}
Error Codes
Common error codes you may encounter when using the API:
- Name
INVALID_PARTICIPANT_ID- Type
- 401
- Description
The participant-id provided is invalid or not registered.
- Name
INVALID_API_KEY- Type
- 401
- Description
The x-api-key provided is invalid or expired.
- Name
VALIDATION_ERROR- Type
- 400
- Description
Request validation failed. Check the error details for specific field errors.
- Name
INVOICE_NOT_FOUND- Type
- 404
- Description
The requested invoice could not be found.
- Name
DUPLICATE_INVOICE- Type
- 409
- Description
An invoice with the same document_identifier already exists.
- Name
FIRS_CONNECTION_ERROR- Type
- 502
- Description
Unable to connect to FIRS platform. Please try again later.
- Name
RATE_LIMIT_EXCEEDED- Type
- 429
- Description
Too many requests. Please slow down and try again.
Rate Limiting
The API implements rate limiting to ensure fair usage and system stability:
- Standard Tier: 100 requests per minute per participant
- Premium Tier: 500 requests per minute per participant
When rate limits are exceeded, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.
Changelog
Version 1.0.0 (July 2025)
- Initial release
- Invoice generation and management endpoints
- Resource data endpoints
- Transmission lookup functionality