E-Invoicing for Nigeria API References

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. It covers B2B, B2C, and B2G transactions, unifying transaction data to provide insights into supply chains, purchasing trends, and financial data to support data-driven fiscal and economic policies.

Technical Compliance:

To comply with the new regulations, businesses must use authorized e-invoicing solutions that integrate with the FIRS platform and meet the technical specifications laid out by FIRS. 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.

These developments underscore Nigeria's commitment to enhancing tax compliance and transparency through digital transformation.

Common Structs

1. Buyer Details `accounting_customer_party`

This contains comprehensive information about the customer to whom the invoice is being issued, including their name, contact details, billing address, and other relevant particulars.

Name
party_name
Type
string
Description
The name of the customer.
Name
tin
Type
string
Description
The TIN Registration number of the customer. (Mandatory)
Name
email
Type
string
Description
The email address of the customer. (Mandatory)
Name
telephone
Type
string (optional)
Description
Phone number of the customer. Must start with + (country code).
Name
business_description
Type
string (optional)
Description
A brief description of the customer's business.
Name
postal_address {}
Type
object
Description
Name
street_name
Type
string
Description
Street address of the customer.
Name
city_name
Type
string
Description
City of the customer.
Name
postal_zone
Type
string
Description
Postal code of the customer.
Name
country
Type
string
Description
Country code of the customer (ISO 3166-1 alpha-2).

2. Line Items `lineitems[]`

This is an array of items inclduded in an invoice. One of such item should have below mentioned data points:

Name
hsn_code
Type
string
Description
Harmonized System Nomenclature (HSN) code.
Name
product_category
Type
string
Description
Category of the product (e.g., "Food and Beverages").
Name
discount_rate
Type
float
Description
Discount rate as a percentage (e.g., 2.01 for 2.01%).
Name
discount_amount
Type
float
Description
Discount amount in applicable currency.
Name
fee_rate
Type
float
Description
Additional fee rate as a percentage.
Name
fee_amount
Type
float
Description
Fixed fee amount in applicable currency.
Name
invoiced_quantity
Type
float
Description
Quantity of items included in the invoice.
Name
line_extension_amount
Type
float
Description
Total amount for the line item before tax.
Name
item {}
Type
object
Description
Name
name
Type
string
Description
Name of the item.
Name
description
Type
string
Description
Description of the item.
Name
sellers_item_identification
Type
string (optional)
Description
Seller’s internal identification of the item.
Name
price {}
Type
object
Description
Name
price_amount
Type
float
Description
Unit price of the item.
Name
base_quantity
Type
float
Description
Base quantity that the price refers to.
Name
price_unit
Type
string
Description
Measurement unit (e.g., "NGN per 1").

POSTng/supplier/onboard

Onboard New Supplier

This endpoint allows you to onboard new supplier to Flick. In this step, you will receive a participant-id that will be required to issue an einvoice.

Request Body

Name
party_name
Type
string
Description
Official Registered Name of the Entity.
Name
tin
Type
string
Description
Registered TIN of the Supplier. (Mandatory)
Name
email
Type
string
Description
Supplier's business email address. (Mandatory)
Name
telephone
Type
string (optional)
Description
Phone number of the supplier. Must start with + (country code).
Name
business_description
Type
string (optional)
Description
A brief description of the supplier's business.
Name
postal_address {}
Type
object
Description
Name
street_name
Type
string
Description
Street address of the supplier.
Name
city_name
Type
string
Description
City name of the supplier.
Name
postal_zone
Type
string
Description
Postal code of the supplier.
Name
country
Type
string
Description
Country code of the supplier (ISO 3166-1 alpha-2).

Sample Request

POST

ng/supplier/onboard

curl --url https://staging-api.flick.network/ng/supplier/onboard \
  --header 'x-flick-auth-key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "party_name": "Dangote Group", 
    "tin": "TIN-0099990001",
    "email": "supplier_business@email.com",
    "telephone": "+23480254099000",
    "business_description": "this entity is into sales of Cement and building materials",
    "postal_address": {
        "street_name": "32, owonikoko street", 
        "city_name": "Gwarikpa", 
        "postal_zone": "023401", 
        "country": "NG" 
    } 
}'

Sample Response

200

Success

{
  "status": "success",
  "message": "Supplier onboarded successfully.",
  "data": {
    "supplier_name": "Test Co.",
    "participant_id": "da5449e9-000a-4376-a603-d664422ac59e"
  }
}

POSTng/einvoice/generate

Generate E-Invoice

To Generate a new E-Invoice, this endpoint can be used along with the participant-id to which it belongs to. Give your onboarded supplier id in header to ensure its reported under that specific device.

Request Body

Name
business_id
Type
string
Description
Unique Business ID for the invoice.
Name
irn
Type
string
Description
Invoice Reference Number.
Name
issue_date
Type
date: YYYY-MM-DD
Description
Date on which the invoice was issued.
Name
due_date
Type
date: YYYY-MM-DD
Description
Due date for payment.
Name
issue_time
Type
time: HH-MM-ss
Description
Time at which the invoice was issued.
Name
invoice_type_code
Type
string
Description
Code representing the invoice type.
Name
payment_status
Type
string
Description
Status of the payment. Defaults to PENDING if not provided.
Name
buyer_reference
Type
string
Description
Reference code for the buyer.
Name
invoice_delivery_period
Type
struct: invoice_delivery_period
Description
Period during which the invoice is valid.
Name
accounting_customer_party
Type
struct: accounting_customer_party
Description
Details of the customer receiving the invoice.
Name
lineitems
Type
struct: lineitems[]
Description
List of line items in the invoice. At least one item is mandatory.

Sample Request

POST

ng/einvoice/generate

curl --url https://staging-api.flick.network/ng/einvoice/generate \
  --header 'x-flick-auth-key: {token}' \
  --header 'participant-id: {participant_-_id}' \
  --header 'Content-Type: application/json' \
  --data '
    {
      "business_id": "4600a55f-8208-4e87-b224-a7a5b48f81db",
      "irn": "IRN-20240514",
      "issue_date": "2024-05-14",
      "due_date": "2024-06-14",
      "invoice_type_code": "396",
      "payment_status": "PENDING",
      "accounting_customer_party": {
          "party_name": "Dangote Group", 
          "tin": "TIN-000001", // now mandatory 
          "email": "business@email.com", // now mandatory 
          "telephone": "+23480254000000", //optional, must start with + (meaning country code) 
          "business_description": "this entity is into sales of Cement and building materials", //optional 
          "postal_address": {
              "street_name": "32, owonikoko street", 
              "city_name": "Gwarikpa", 
              "postal_zone": "023401", 
              "country": "NG" 
          } 
      },
      "invoice_line": [
        {
          "hsn_code": "CC-001",
          "product_category": "Food and Beverages",
          "discount_rate": 2.01,
          "discount_amount": 0.603,
          "invoiced_quantity": 15,
          "line_extension_amount": 30,
          "item": {
            "name": "item name",
            "description": "item description"
          },
          "price": {
            "price_amount": 10,
            "base_quantity": 3,
            "price_unit": "NGN per 1"
          }
        }
      ]
    }'

Sample Response

200

Success

    {
    "status": "success",
    "message":{
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "qr_code": "kjiJ34xI+od12zBmUx1eYZHgBtx9KnJiQ43tRHk67WiWv2xopjQlJnfsxPI7BnRk..."
    }
  }

E-Invoicing for Nigeria API References

Introduction

Technical Compliance:

Common Structs

1. Buyer Details accounting_customer_party

2. Line Items lineitems[]

Onboard New Supplier

Request Body

Sample Request

Sample Response

Generate E-Invoice

Request Body

Sample Request

Sample Response

1. Buyer Details `accounting_customer_party`

2. Line Items `lineitems[]`