-
About
- API Version: v1.4
- Help Document Version: v1.2.6
- Last Updated: 12 March, 2026
-
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)
*"govt_code": "NG-AB-ANO" --String, The Local Govt code representing the buyer's Local Govt Code.
*"state_code": "NG-AB" --String, The State code representing the buyer's state in country.
}, -- 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 NRS
*"product_category": "Electronics", --String, Electronics, Food and Beverages etc. Provided by NRS
*"is_service": false --Bool, Does Sold item is Good or Service,
*"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",
"is_service":false,
"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 NRS
*"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 NRS 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 |
| -1001 |
Failed to parse byte response to object |
| -1002 |
Invalid document type |
| -1003 |
Failed to make request object bytes for invoice |
| -1004 |
Failed to generate response bytes for sign result |
| -1005 |
Failed to read request body |
| -1006 |
Request object is null |
| -1008 |
Required headers are missing |
| -1009 |
Failed to save transaction |
| -1010 |
Failed to check duplicacy of invoice |
| -1011 |
Failed to make request object bytes |
| -1012 |
Failed to report VAT for invoice |
| -1013 |
Failed to update status of receipt |
| -1014 |
Failed to find receipt with associated IRN |
| -1015 |
Failed to parse sign response |
| -1016 |
Failed to update invoice status to signed |
| -1017 |
Error occurred while signing receipt |
| -1018 |
Failed to parse response JSON for receipt |
| -1019 |
Failed to update invoice status to VAT reported |
| -1020 |
Failed to get receipt data |
| -1021 |
Failed to update invoice status to transmitted |
| -1022 |
Error while getting credentials |
| -1023 |
Error occurred while downloading invoice |
| -1024 |
Failed to decrypt downloaded invoice |
| -1025 |
Failed to parse decrypted downloaded invoice |
| -1026 |
Failed to make request object bytes for HSN codes |
| -1027 |
Failed to make request object bytes for countries |
| -1028 |
Failed to make request object bytes for currencies |
| -1029 |
Failed to make request object bytes for tax category |
| -1030 |
Failed to make request object bytes for invoice types |
| -1031 |
Failed to make request object bytes for payment means |
| -1032 |
Error occurred while fetching currencies |
| -1033 |
Error occurred while fetching countries |
| -1034 |
Error occurred while fetching HSN |
| -1035 |
Error occurred while fetching VAT exempt HSN |
| -1036 |
Error occurred while fetching tax categories |
| -1037 |
Error occurred while fetching invoice types |
| -1038 |
Error occurred while fetching payment means |
| -1039 |
Error occurred while transmitting invoice |
| -1040 |
Failed to find details of duplicate receipt |
| -1041 |
Receipt currency mismatch |
| -1042 |
Customer TIN mismatch |
| -1043 |
Receipt date mismatch |
| -1044 |
Receipt number mismatch |
| -1045 |
Receipt type mismatch |
| -1046 |
Receipt subtotal mismatch |
| -1047 |
Receipt total mismatch |
| -1048 |
Receipt item count mismatch |
| -1049 |
Receipt tax net mismatch |
| -1050 |
Receipt tax value mismatch |
| -1051 |
Receipt tax count mismatch |
| -1052 |
Failed to parse request bytes to object |
| -1053 |
Invalid invoice number |
| -1054 |
Null or empty invoice number |
| -1055 |
Invalid merchant service ID |
| -1056 |
Invalid time stamp |
| -1057 |
Failed to read request |
| -1058 |
Failed to make JSON bytes for QR |
| -1060 |
Null or empty request body |
| -1061 |
Error while decoding public key |
| -1062 |
Failed to decrypt required credentials |
| -1063 |
Invalid receipt number |
| -1064 |
Invalid receipt date |
| -1065 |
Invalid business ID |
| -1066 |
Invalid receipt currency |
| -1067 |
Null or empty invoice items |
| -1068 |
Null or empty tax details |
| -1069 |
Receipt tax net error |
| -1070 |
Receipt tax value error |
| -1071 |
No item found for given tax details |
| -1072 |
Receipt subtotal mismatch with calculated subtotal |
| -1073 |
Receipt total mismatch with calculated total |
| -1074 |
Null or empty items |
| -1075 |
Invalid reference invoice |
| -1076 |
Invalid QR generated |
| -1077 |
Invalid IRN generated |
| -1081 |
Invalid SI API key |
| -1082 |
Invalid SI client key |
| -1083 |
Invalid IRN received |
| -1084 |
Failed to make request object bytes for service codes |
| -1085 |
Failed to make request object bytes for local governments |
| -1086 |
Failed to make request object bytes for states |
| -1087 |
Error occurred while fetching service codes |
| -1088 |
Error occurred while fetching local governments |
| -1089 |
Error occurred while fetching states |
| -1090 |
Failed to check duplicacy of webhook data |
| -1093 |
Failed to find subscriber details |
| -1094 |
Merchant TIN mismatched |
| -1095 |
Invalid merchant TIN for session authentication |
| -1096 |
Failed to get vendor details |
| -1097 |
Vendor details not found |
| -1098 |
Invalid merchant TIN |
| -1099 |
Failed to get customer details |
| -1100 |
Invalid certificate |
| -1101 |
Invalid public key |
| -1104 |
Invalid QR received |
| -1107 |
Subscription is not in active state |
| -1108 |
Failed to fetch required merchant details |
| -1109 |
Model type mismatch detected |
| -1110 |
Model type parsing process failed |
| -1111 |
Subscription type APP |
| -1112 |
Subscription type APSI |
| -1117 |
Error occurred while updating subscription meta reference date |
| -1118 |
Null or empty model type detected |
| -1119 |
Error while fetching client details |
| -1120 |
Client ID header is missing or invalid |
| -1122 |
Failed to delete transaction |
| -1123 |
VFD access key is not in active state |
|
|
|
| |
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 |
