-
About
- API Version: v1.3
- Help Document Version: v1.2.4
- Last Updated: 09 December, 2025
-
How to setup environment
- The client-server communication will be via a REST API on HTTPS. Just use any standards based client library e.g. cURL to connect to the server.
-
Test Portal Base URLs
- Base API URL: https://demo.smartvat.net/firs/api/core
|
POST /sign |
| The Sign API request will be combination of multiple actions. It will be processing Sign Request for generating
IRN, QR Code, Signing Receipt and Reporting VAT etc.
The receipt gets validated at server, i.e. server calculates total tax net/value,
subtotal, grandtotal considering each item's price/tax type and verifies whether the
calculated values match the respective values received in sign request. |
{
*"vendor_tin": "68452114-4234", --String, Merchant TIN.
*"receipt_number": "INV1231", --String, The identifier generated by the taxpayer’s accounting system. Only digits and capital alphabets are allowed.
*"receipt_type": "1", --Integer, Type of receipt: 1 - Invoice, 2 - Credit Note, 3 - Debit Note
*"currency": "NGN" --String, Receipt Currency
*"date": "2025-07-22", --String, The date, assigned by the sender, on which this document was issued. Must be in YYYY-MM-DD format
*"time": "13:00:00", --String, Document Time, Must be in HOURS (24HRS FORMAT)-MINUTES-SECONDS
*"accounting_customer_party": { **Customer details are only required in B2B Transactions.
*"party_name": "Vada Wilkinson" --String, The registered name of the buyer (taxpayer) receiving the invoice.
*"tin": "68452114-4234" --String, The Taxpayer Identification Number (TIN) assigned to the buyer for tax compliance.
*"email":"customer@example.com" --String, The buyer’s official email address used for communication regarding invoices and tax compliance.
*"telephone": "+1234567890" --String, The buyer's contact number with the country code prefix (+234 for Nigeria).
*"business_description": "Retail" --String, A brief description of the business's line of business.
"postal_zone": "12345" --String, The postal code of the buyer’s business location.
*"country": "NG" --String, The country code representing the buyer's registered country. String (ISO 3166-1 Alpha-2)
}, -- If Customer(s) exist on SmartVat Protal, Only Customer TIN would be enough. All other required data will be fetched and utilized from server.
"reference_details": [ --Links the invoice to previous billing documents (e.g., credit notes, debit notes, or prior invoices). Array of objects with IRN and date
{
"irn": "INV1011-7A0819F4-20250506" --String, System Integrater generated IRN associated to refered Document
"issue_date": "2025-05-06" --String, Issue Date of Document. Must be in YYYY-MM-DD format
}
...
...
]
*"items": [ --List of items
{
*"hsn_code": "8502.40", --String, HSN Code Provided by FIRS
*"product_category": "Electronics", --String, Electronics, Food and Beverages etc.
*"invoiced_quantity": 10, --Float, Invoiced Quantity
*"item_name" : "Wireless Mouse", --String, Sold Item
*"item_desc" : "Ergonomic wireless mouse", --String, Item Description
*"item_identification": "SKU-001", --String, Item Identification. The seller’s internal SKU (Stock Keeping Unit).
*"item_price": 100.00, --Float, Item Price (Before taxes)
"discount_rate": 0.00, --Float, Item Discount
"discount_price": 0.00, --Float, Discounted Price
"fee_rate": 0.00, --Float, Applicable fee percentage
"fee_amount": 0.00, --Float, Fee Amount
*"tax_code": "STANDARD_VAT", --String, Tax Code Applicable on Item,
*"tax_percent": 7.5, --Float, Applicatbe Tax Percentage
*"item_amount_total": 1000.00, --Float, item_price * invoiced_quantity
},
{
"hsn_code": "8419.5000",
"product_category": "Educational Books",
"invoiced_quantity": 10,
"item_name" : "Class 10 World History",
"item_desc" : "World history book",
"item_identification": "SKU-003",
"item_price": 100.00,
"discount_rate": 0.00,
"discount_price": 0.00,
"fee_rate": 0.00,
"fee_amount": 0.00,
"tax_code": "ZERO_VAT",
"tax_percent": 0.0,
"item_amount_total": 1000.00,
},
...
...
],
*"taxes": [ --List of all taxes used in Document and its details
{
*"tax_code": "STANDARD_VAT", --String, HSN Code Provided by FIRS
*"tax_percent": 7.5, --Float, Applicable Tax Percetage
*"tax_net": 2000.00, --Float, Totals of all item lines, falling under same Tax
*"tax_value" : 150.00, --Float, Total calculated tax on given Tax
},
{
"tax_code": "ZERO_VAT",
"tax_percent": 0.00,
"tax_net": 1000.00,
"tax_value" : 0.00,
},
...
...
],
*"subtotal": 3000.00, --Float, Total before Taxes
"subtotal_discount": 0.0, --Float, Subtotal Discount before Taxes
*"total": 3150.00, --Float, Document Total/Amount Payable
}
|
| The Sign API response structure is given as Following. |
{
"errorCode": 0, --Integer, Error Code, 0 means success, otherwise will have some error code
"errorMsg":"" --String, Error Message,if error code is not 0
"exceptionMsg":"" --String, Exception Message if Any
"responseData": {
"irn": "INV1071-7A0819F4-20250818", --String, Unique IRN for Document
"qr_code": "YP2nnG/imEpjQmIox/..............", --String, QR Code To be printed on Document, can be scanned using MBS 360 mbole app.
"warning_code": 0, --String, 0 means success, otherwise will have some warning Code/
"warning": "", --String, Warning Message.
"receipt_status": 4 --Integer, 1 -Initaited, 2- Sign Success, 3- Vat Reported Success, 4- Transmit Success
"is_duplicate": false,
},
}
|
Request Parameters
| - |
Request Stream |
Request stream containing json comprising of request data. |
Yes |
| acess-key |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| client-id |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| model-type |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
Response Code
| 200 |
Success HTTP response code |
| Any other HTTP error code |
Other HTTP codes have their usual meanings+ |
| - |
Response Stream |
The stream contents will be a json byte stream. |
|
|
|
| |
GET /hsn |
Description
This API is HTTP GET request and is used to get HSN Codes from FIRS Server.
| This API requires `client-id`, `access-key` and `model-type` header parameters for the request is shown below. |
{
"errorCode":0, --Integer, Error Code, 0 means success, otherwise will have some error code
"responseData": [
{
"hscode": "0101.21", --String, HSN Code
"description": "Horses; live, pure-bred breeding animals" --String, HSN Description
},
{
"hscode": "0101.29",
"description": "Horses; live, other than pure-bred breeding animals"
},
......
......
......
]
"errorMsg":"" --String, Error Message,if error code is not 0, Empty otherwise
"exceptionMsg":"" --String, Exception Message if Any, Empty otherwise
}
|
Request Parameters
| acess-key |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| client-id |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| model-type |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
Response Code
| 200 |
Success HTTP response code |
| Any other HTTP error code |
Other HTTP codes have their usual meanings+ |
| - |
Response Stream |
The stream contents will be a json byte stream. |
|
|
|
| |
GET /hsn-vatexempt |
Description
This API is HTTP GET request and is used to get HSN Codes which are VAT-Exempt.
| This API requires `client-id`, `access-key` and `model-type` header parameters for the request is shown below. |
{
"errorCode":0, --Integer, Error Code, 0 means success, otherwise will have some error code
"responseData": [
{
"heading_no": "29.15",
"harmonized_system_code": "2915.3100", --String, HSN Code
"tariff_category": "MEDICAL, VENTIRINARY AND PHARMACEUTICAL RAW MATERIALS AND PRODUCTS",
"tariff": "Ethyl acetate",
"description": "Saturated acyclic monocarboxylic acids --String, HSN Description
and their derivatives."
},
{
"heading_no": "29.16",
"harmonized_system_code": "2916.3900",
"tariff_category": "MEDICAL, VENTIRINARY AND PHARMACEUTICAL RAW MATERIALS AND PRODUCTS",
"tariff": "Others",
"description": "unsaturated Acyclic monocarboxylic acids"
},
......
......
......
]
"errorMsg":"" --String, Error Message,if error code is not 0, Empty otherwise
"exceptionMsg":"" --String, Exception Message if Any, Empty otherwise
}
|
Request Parameters
| acess-key |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| client-id |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| model-type |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
Response Code
| 200 |
Success HTTP response code |
| Any other HTTP error code |
Other HTTP codes have their usual meanings+ |
| - |
Response Stream |
The stream contents will be a json byte stream. |
|
|
|
| |
GET /servicecodes |
Description
This API is HTTP GET request and is used to get all aplicable Service Codes with details.
| This API requires `client-id`, `access-key` and `model-type` header parameters for the request is shown below. |
{
"errorCode":0, --Integer, Error Code, 0 means success, otherwise will have some error code
"responseData": [
{
"code": "0112", --String Service Codes
"description": "Growing of rice" --String Description of Service
},
{
"code": "0114",
"description": "Growing of sugar cane"
},
{
"code": "0115",
"description": "Growing of tobacco"
},
{
"code": "0116",
"description": "Growing of fibre crops"
},
......
......
......
]
"errorMsg":"" --String, Error Message,if error code is not 0, Empty otherwise
"exceptionMsg":"" --String, Exception Message if Any, Empty otherwise
}
|
Request Parameters
| acess-key |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| client-id |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| model-type |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
Response Code
| 200 |
Success HTTP response code |
| Any other HTTP error code |
Other HTTP codes have their usual meanings+ |
| - |
Response Stream |
The stream contents will be a json byte stream. |
|
|
|
GET /taxes |
Description
This API is HTTP GET request and is used to get all aplicable taxes with details.
| This API requires `client-id`, `access-key` and `model-type` header parameters for the request is shown below. |
{
"errorCode":0, --Integer, Error Code, 0 means success, otherwise will have some error code
"responseData": [
{
"code": "STANDARD_VAT", --String, Tax Code
"value": "Standard Value-Added Tax", --String, Description
"percent": "7.5" --String, Percentage
},
{
"code": "REDUCED_VAT",
"value": "Reduced Value-Added Tax",
"percent": "7.5"
},
{
"code": "ZERO_VAT",
"value": "Zero Value-Added Tax",
"percent": "0.0"
},
......
......
......
]
"errorMsg":"" --String, Error Message,if error code is not 0, Empty otherwise
"exceptionMsg":"" --String, Exception Message if Any, Empty otherwise
}
|
Request Parameters
| acess-key |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| client-id |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| model-type |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
Response Code
| 200 |
Success HTTP response code |
| Any other HTTP error code |
Other HTTP codes have their usual meanings+ |
| - |
Response Stream |
The stream contents will be a json byte stream. |
|
|
|
| |
GET /currencies |
Description
This API is HTTP GET request and is used to get Currency Details.
| This API requires `client-id`, `access-key` and `model-type` header parameters for the request is shown below. |
{
"errorCode":0, --Integer, Error Code, 0 means success, otherwise will have some error code
"responseData": [
{
"symbol": "$",
"name": "US Dollar",
"symbol_native": "$",
"decimal_digits": 2,
"rounding": 0,
"code": "USD", --String, Currency Code
"name_plural": "US dollars"
},
{
"symbol": "CA$",
"name": "Canadian Dollar",
"symbol_native": "$",
"decimal_digits": 2,
"rounding": 0,
"code": "CAD",
"name_plural": "Canadian dollars"
},
{
"symbol": "€",
"name": "Euro",
"symbol_native": "€",
"decimal_digits": 2,
"rounding": 0,
"code": "EUR",
"name_plural": "euros"
},
......
......
......
]
"errorMsg":"" --String, Error Message,if error code is not 0, Empty otherwise
"exceptionMsg":"" --String, Exception Message if Any, Empty otherwise
}
|
Request Parameters
| acess-key |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| client-id |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| model-type |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
Response Code
| 200 |
Success HTTP response code |
| Any other HTTP error code |
Other HTTP codes have their usual meanings+ |
| - |
Response Stream |
The stream contents will be a json byte stream. |
|
|
|
| |
GET /getcountries |
Description
This API is HTTP GET request and is used to get Country List.
| This API requires `client-id`, `access-key` and `model-type` header parameters for the request is shown below. |
{
"errorCode":0, --Integer, Error Code, 0 means success, otherwise will have some error code
"responseData": [
{
"name": "Afghanistan",
"alpha_2": "AF",
"alpha_3": "AFG",
"country_code": "004",
"iso_3166_2": "ISO 3166-2:AF",
"region": "Asia",
"sub_region": "Southern Asia",
"intermediate_region": "",
"region_code": "142",
"sub_region_code": "034",
"intermediate_region_code": ""
},
{
"name": "Åland Islands",
"alpha_2": "AX",
"alpha_3": "ALA",
"country_code": "248",
"iso_3166_2": "ISO 3166-2:AX",
"region": "Europe",
"sub_region": "Northern Europe",
"intermediate_region": "",
"region_code": "150",
"sub_region_code": "154",
"intermediate_region_code": ""
},
......
......
......
]
"errorMsg":"" --String, Error Message,if error code is not 0, Empty otherwise
"exceptionMsg":"" --String, Exception Message if Any, Empty otherwise
}
|
Request Parameters
| acess-key |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| client-id |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
| model-type |
Request Header |
To be provided to Merchant after successfully onbarding. |
Yes |
Response Code
| 200 |
Success HTTP response code |
| Any other HTTP error code |
Other HTTP codes have their usual meanings+ |
| - |
Response Stream |
The stream contents will be a json byte stream. |
|
|
|
| |
Error Code List |
| -1000 |
System Error occurred. If error persist, please contact support |
| -1001 |
Failed to parse request bytes to object. Please contact support |
| -1002 |
Invalid Document type |
| -1004 |
Failed to make request object for Invoice. |
| -1005 |
Failed to make Request for IRN. |
| -1006 |
Failed to generate response bytes for Sign result. |
| -1007 |
Failed to read request body. |
-1008 |
Request object is null. |
| -1009 |
Failed to parse response JSON for IRN |
| -1010 |
Failed to parse IRN Response. |
|
| -1011 |
Failed to generate response bytes for IRN |
|
| -1012 |
Invalid action type |
|
| -1013 |
Required headers are missing |
| -1014 |
Failed to save Transaction |
| -1015 |
Failed to check duplicacy of Receipt |
| -1016 |
Failed to make request object bytes for VAT Report request |
| -1017 |
Failed to report VAT for receipt |
| -1018 |
Failed to update status of receipt |
| -1019 |
Failed to find receipt with associated IRN |
| -1020 |
Failed to generate response bytes for verification result |
| -1021 |
Error occurred while verifying receipt |
| -1022 |
Failed to parse verification response |
| -1023 |
Failed to parse sign response |
| -1024 |
Failed to update invoice status to Signed |
| -1025 |
Error occurred while signing receipt |
| -1026 |
Failed to parse response json for receipt |
| -1027 |
Unknown action for parsing response |
| -1028 |
Failed to update invoice status to VAT REPORTED |
| -1030 |
Failed to get receipt data |
|
|
|
| |
HTTP Status Code List |
| 400 |
Bad request i.e. the request received from the client is incomplete or not in prescribed format |
| 401 |
Unauthorized i.e. the request received contains wrong or expired credentials |
| 403 |
Forbidden i.e. the request received is trying to access a resource belonging to other user |
| 500 |
Internal server error i.e. the server experienced some unexpected error while processing the request |
|
|
|
| * denotes mandatory field |
