Validate & Sign Invoice

base_url: https://firseinvoice.etranzactng.com/

Description: This endpoint validates the content of the invoice to ensure compliance with FIRS requirements and then sent to FIRS for signing. All data points follow the Universal Business Language (UBL) standard.

Sample Request
Sample Response

Request Parameters

Parameter	Type	Description	Required
business_id	string	Unique alphanumeric ID generated when the business is registered on the e-invoicing platform. It allows the system recognize all invoices generated by the company	Yes
irn	string	A unique tracking number assigned to each invoice.	Yes
issue_date	string	The date assigned by the sender on which the invoice was issued (YYYY-MM-DD).	Yes
due_date	string	The date on which the Invoice is due for payment (YYYY-MM-DD).	No
issue_time	string	The time assigned by the sender at which this document was issued (HH:MM:SS 24h format).	No
invoice_type_code	string	A numeric code representing the type of invoice issued. (See Resources: 1.5.1 for invoice types)	Yes
payment_status	string	Invoice payment status. Where 0 = REJECTED 1 = PENDING 2 = PAID	Yes
note	string	Free-form encrypted text with extra invoice information.	No
tax_point_date	string	The actual date when the tax becomes applicable (YYYY-MM-DD).	No
document_currency_code	string	The default currency in which the invoice is issued.	Yes
tax_currency_code	string	The currency in which tax amounts are calculated.	Yes
accounting_cost	float	Represents the accounting category or cost center assigned to the transaction.	No
buyer_reference	string	A reference number or code provided by the buyer to track the invoice.	No
invoice_delivery_period	object	Defines start and end dates for delivery of goods/services.	No
start_date	string	Start date for delivery of goods/services.	Yes
end_date	string	End dates for delivery of goods/services.	Yes
order_reference	string	The order number tied to an invoice. Reference to related sales order.	No
billing_reference	array	Links invoice to previous billing invoice/document (requires IRN and issue_date).	No
dispatch_document_reference	object	Refers to a despatch advice document used for tracking shipment (requires IRN and issue_date).	No
receipt_document_reference	object	Reference to a receipt advice associated with the invoice (requires IRN and issue_date).	No
originator_document_reference	object	Identifies the original document that initiated the invoice (requires IRN and issue_date).	No
contract_document_reference	array	References to related contract documents. (requires IRN and issue_date).	No
additional_document_reference	object	General reference field for additional related documents. (requires IRN and issue_date).	No
accounting_supplier_party	object	Seller/supplier details issuing the invoice.	Yes
accounting_supplier_party.party_name	string	Legal name of supplier/customer.	Yes
accounting_supplier_party.tin	string	Tax Identification Number (TIN) is a unique number issued by FIRS (or JTB/SBIR) for filing tax returns and other tax-related transactions	Yes
accounting_supplier_party.email	string	Email Address	Yes
accounting_supplier_party.telephone	string	Contact phone number (with country code prefix).	No
accounting_supplier_party.business_description	string	Description of the entity’s business.	No
accounting_supplier_party.postal_address	object	Postal address of supplier/customer.	Yes
accounting_supplier_party.postal_address.street_name	string	Street address.	Yes
accounting_supplier_party.postal_address.city_name	string	City name	Yes
accounting_supplier_party.postal_address.postal_zone	string	Postal/ZIP code.	Yes
accounting_supplier_party.postal_address.lga	string	Local Government Code	Yes
accounting_supplier_party.postal_address.state	string	State Code	Yes
accounting_supplier_party.postal_address.state	string	Country Code	Yes
accounting_customer_party	object	Buyer or recipient details (party name TIN contact address).	No
payee_party	object	Payment receiver entity details (if different).	No
bill_party	object	Billing entity details (if different). If the payment goes to someone else, this field captures that entity's details.	No
ship_party	object	Shipping entity details.	No
tax_representative_party	object	Tax agent details handling invoicing/compliance. If a business has a tax agent handling invoicing and compliance, their details are entered here.	No
actual_delivery_date	string	The date the goods or services were delivered (Format: YYYY-MM-DD).	No
payment_means	array	Defines how the invoice will be paid and when payment is due. (payment means code + due date).	No
payment_terms_note	string	Payment terms and conditions description.	No
allowance_charge	array	Defines any discounts (allowance) or extra charges.	No
tax_total	array	Total tax charged on the invoice (with subtotals by category).	Yes
tax_amount	float	The total tax charged on the invoice (the actual tax applied on the taxable amount). If a business sells multiple items, this is the total tax applied across all items.	Yes
tax_subtotal	array	This section breaks down the tax into different tax categories. If an invoice contains VAT-exempt and VAT-applicable goods, only taxable items will appear here.	No
taxable_amount	integer	The total value of goods/services on which tax is calculated.	Yes
tax_category	array	Specifies what type of tax is applied to this subtotal. (See resources)	Yes
legal_monetary_total	object	The total payable amount (inclusive/exclusive of tax).	Yes
invoice_line	array	Details about each item or service being invoiced.	Yes
item	array	A collection of product/service details included in the invoice line.	Yes
description	array	List of product details (each object contains product metadata).	Yes

Note

The JSON/object structure is the same for all the six (accounting_customer_party, payee_party, bill_party, ship_party and tax_representative_party inclusive) however only the supplier party (accounting_supplier_party) detail is marked as mandatory/compulsory by FIRS.

The rest are optional – however if you provide either of them then the parameters/values included in the object also have some parameters as optional and others mandatory (see sample request).

invoice_line(array)

Parameter	Type	Description	Required?
hsn_code	integer	Harmonized System of Nomenclature (HSN) code for item classification.	Yes
product_category	string	Category of product/service	Yes
discount_rate	float	Discount percentage applied to item.	No
discount_amount	float	Absolute monetary value of the discount (in currency) amount	No
fee_rate	float	Fee/charge percentage applied to item	No
fee_amount	float	Absolute fee/charge amount.	No
invoiced_quantity	integer	Quantity of items invoiced	Yes
line_extension_amount	integer	The total amount of all invoice items before tax and any discounts/charges.	Yes
item	array	TA collection of product/service details included in the invoice line. Details of the invoiced item.	Yes
price	object	Price details for this line.	Yes
price.price_amount	float	The cost per item or service unit. The price value applied to the base_quantity value.	Yes
price.base_quantity	integer	The quantity to which the price_amount value applies (e.g. for bulk/package pricing)	Yes
price.price_unit	string	A representation of the pricing unit with currency (mainly for human readability)	Yes

item(array)

Parameter	Type	Description	Required?
name	string	Name of the item	Yes
description	string	Description of the item	No
sellers_item_identification	string	Seller’s unique internal reference/SKU for identifying product/service (optional but useful for mapping with inventory/ERP)	No

payment_means(array)

Parameter	Type	Description	Required?
payment_means_code	string	Code representing the payment method used. (See Resources: payment means)	Yes
payment_due_date	date	Due date for the payment	Yes

allowance_charge(array)

Parameter	Type	Description	Required?
amount	float	Value of the allowance or charge	Yes
charge_indicator	boolean	True implies charge added. False implies allowance (discount) subtracted.	Yes

tax_total(array)

Parameter	Type	Description	Required?
tax_amount	float	The total tax charged on the invoice (the actual tax applied on the taxable amount). If a business sells multiple items, this is the total tax applied across all items.	Yes
tax_subtotal	float	This section breaks down the tax into different tax categories. If an invoice contains VAT-exempt and VAT- applicable goods, only taxable items will appear here.	Yes

tax_subtotal(array)

Parameter	Type	Description	Required?
taxable_amount	float	The total value of goods/services on which tax is calculated.	Yes
tax_amount	boolean	The total tax charged on the invoice (the actual tax calculated/applied on the taxable_amount). If a business sells multiple items, this is the total tax applied across all items.	Yes
tax_category	array	Specifies what type of tax is applied to this subtotal. (See resources: tax categories)	Yes

tax_category(array)

Parameter	Type	Description	Required?
id	string	Tax category identifier	Yes
percent	float	Tax rate Yes (Example: 2.3 for 2.3%).	Yes

legal_monetary_total(array)

Parameter	Type	Description	Required?
line_extension_amount	float	Total amount of all invoice items/line extensions before tax and any discounts/charges.	Yes
tax_exclusive_amount	float	Invoice total before tax.	Yes
tax_inclusive_amount	float	Invoice total after tax.	Yes
payable_amount	float	The final amount the buyer must pay after applying discounts, charges, and tax.(usually equal to tax inclusive).	Yes

Response Parameters

Parameter	Type	Description	Required?
status	integer	HTTP status code	Yes
message	string	Description of http status code	Yes
execTime	integer	Time taken to process request (for metrics and performance tracking).	Yes
error	integer	Specific errors when request does not return a HTTP status of 200.	No

Sample Request
Sample Response

Request Parameters

POST {base_url}/api/v1/app/invoice/validate
curl -X POST
  -H "X-API-Key: {{CLIENT_API_KEY}}"
  -H "X-API-Signature: {{HMAC_SHA256_SIGNATURE}}"
  -H "X-API-Timestamp: {{ISO_20022_TIMESTAMP}}"
  -H "Content-Type: application/json"
  -d '{
    "business_id": "6f19a0f0-c8f3-4d2b-8a8b-1b2c45e89d0f",
    "irn": "INV285-47AT78FN-20250417",
    "issue_date": "2025-08-01",
    "due_date": "2025-08-08",
    "issue_time": "14:10:04",
    "invoice_type_code": "396",
    "payment_status": "PENDING",
    "note": "sample note (will be encrypted)", // Optional
    "tax_point_date": "2025-08-01",
    "document_currency_code": "NGN",
    "tax_currency_code": "NGN",
    "accounting_cost": "2000 NGN",
    "buyer_reference": "BUYREF-12345",
    "order_reference": "ITW001-E9E0C0D3-20240619",
    "invoice_delivery_period": {
        "start_date": "2025-08-01",
        "end_date": "2025-08-07"
    },
    "billing_reference": [ // Optional
        {
            "irn": "ITW001-E9E0C0D3-20240619",
            "issue_date": "2024-05-14"
        }
    ],
    "dispatch_document_reference": { // Optional
        "irn": "IXTDISP-B457EFE1-20250731",
        "issue_date": "2025-07-31"
    },
    "receipt_document_reference": { // Optional
        "irn": "IVRCPT-B457EFE1-20250731",
        "issue_date": "2025-07-31"
    },
    "originator_document_reference": { // Optional
        "irn": "CRORIG-B457EFE1-20250730",
        "issue_date": "2025-07-30"
    },
    "contract_document_reference": { // Optional
        "irn": "MJCONT-B457EFE1-20250729",
        "issue_date": "2025-07-29"
    },
    "additional_document_reference": [ // Optional
        {
            "irn": "TXDOC-B457EFE1-20250731",
            "issue_date": "2025-07-28"
        }
    ],
    "accounting_supplier_party": {
        "party_name": "Felidan Gross Nig. Ltd",
        "tin": "TIN-0099990001",
        "email": "supplier@felidangroup.com",
        "telephone": "+23480254099000",
        "business_description": "Telecom services and data solutions",
        "postal_address": {
            "street_name": "173 Courtney Street, Victoria Island",
            "city_name": "Lagos",
            "postal_zone": "100001",
            "country": "NG"
        }
    },
    "accounting_customer_party": { // Optional
        "party_name": "Dangote Group",
        "tin": "TIN-000001",
        "email": "business@dangote.com",
        "telephone": "+23480254000000",
        "business_description": "Cement and building materials",
        "postal_address": {
            "street_name": "1, Dangote Avenue",
            "city_name": "Abuja",
            "postal_zone": "900001",
            "country": "NG"
        }
    },
    "payee_party":{ // Optional
        "party_name": "Mega Logistics",
        "tin": "45678901-0003",
        "email": "dispatch@megalogistics.net",
        "telephone": "+81312345678",
        "business_description": "Shipping and Logistics",
        "postal_address": {
            "street_name": "2-3-4 Akasaka",
            "city_name": "Minato-ku",
            "postal_zone": "107-0052",
            "country": "JP"
        }
    },
    "bill_party":{ // Optional
        "party_name": "ABC Holdings Ltd",
        "tin": "89487982-0001",
        "email": "paytest@email.com",
        "telephone": "+23480254000000",
        "business_description": "Holding Company",
        "postal_address": {
            "street_name": "45 Marina Road",
            "city_name": "Ikeja",
            "postal_zone": "101233",
            "country": "NG"
        }
    },
    "ship_party":{ // Optional
        "party_name": "XYZ Corporation",
        "tin": "12345678-0001",
        "email": "info@xyzcorp.com",
        "telephone": "+12125551234",
        "business_description": "Software and IT Services",
        "postal_address": {
            "street_name": "100 Main Street",
            "city_name": "New York",
            "postal_zone": "10001",
            "country": "US"
        }
    },
    "tax_representative_party":{
        "party_name": "Global Solutions Inc.",
        "tin": "98765432-0002",
        "email": "contact@globalsolutions.com",
        "telephone": "+442079460123",
        "business_description": "Consulting Firm",
        "postal_address": {
            "street_name": "500 Regents Lane",
            "city_name": "London",
            "postal_zone": "SW1A 0AA",
            "country": "GB"
        }
    },
    "actual_delivery_date": "2025-08-05",
    "payment_means": [ // Optional
        {
            "payment_means_code": "43",
            "payment_due_date": "2025-08-10"
        }
    ],
    "payment_terms_note": "Payment within 7 days of issue", // Optional
    "allowance_charge": [  // Optional
        {
            "charge_indicator": true,
            "amount": 800.6
        },
        {
            "charge_indicator": false,
            "amount": 10
        }
    ],
    "tax_total": [ 
        {
            "tax_amount": 20.71,
            "tax_subtotal": [
                {
                    "taxable_amount": 900.6,
                    "tax_amount": 20.71,
                    "tax_category": {
                        "id": "LOCAL_SALES_TAX",
                        "percent": 2.3
                    },
                    "tax_category_percent": 2.3
                }
            ]
        }
    ],
    "legal_monetary_total": { 
        "line_extension_amount": 110,
        "tax_exclusive_amount": 900.60,
        "tax_inclusive_amount": 921.31,
        "payable_amount": 921.31
    },
    "invoice_line": [ 
        {
            "item": {
                "name": "300mm Cables",
                "description": "300mm cables for servicing [stdx10]",
                "sellers_item_identification": "XTZ-2471"
            }, 
            "price": {
                "price_amount": 6000,
                "base_quantity": 1,
                "price_unit": "NGN per 1"
            },
        "hsn_code": "CC-058",
        "product_category": "Telecom Equipment",
        "discount_rate": 2.01,
        "discount_amount": 3500,
        "fee_rate": 1.01,
        "fee_amount": 50,
        "invoiced_quantity": 15,
        "line_extension_amount": 50
        }, 
        {
            "item": {
                "name": "Iron Rod 12mm",
                "description": "Steel rods for telecom tower construction",
                "sellers_item_identification": "DTN-171"
            }, 
            "price": {
                "price_amount": 4000,
                "base_quantity": 1,
                "price_unit": "NGN per 1"
            },
        "hsn_code": "CC-018",
        "product_category": "Telecom Accessories",
        "discount_rate": 1.5,
        "discount_amount": 2000,
        "fee_rate": 1.01,
        "fee_amount": 50,
        "invoiced_quantity": 15,
        "line_extension_amount": 60 
        }
    ]
   }
'

Sample Success Response

POST {base_url}/api/v1/app/invoice/validate
{
    "status": 200,
    "message": "Invoice signed successfully",
    "execTime": 1.388868,
    "error": ""
}

Validate & Sign Invoice

base_url: https://firseinvoice.etranzactng.com/​

Request Parameters​

invoice_line(array)​

item(array)​

payment_means(array)​

allowance_charge(array)​

tax_total(array)​

tax_subtotal(array)​

tax_category(array)​

legal_monetary_total(array)​

Response Parameters​

Request Parameters​

Sample Success Response​

base_url: https://firseinvoice.etranzactng.com/

Request Parameters

invoice_line(array)

item(array)

payment_means(array)

allowance_charge(array)

tax_total(array)

tax_subtotal(array)

tax_category(array)

legal_monetary_total(array)

Response Parameters

Request Parameters

Sample Success Response