Third Party Insurance API
This section contains the recommended flow for integrating third party motor insurance services on the VTpass RESTful API.
Authentication
The VTpass API uses Basic Authentication.
It should be passed as a concatenated string like this
username:password
Please use the following details for authentication
Username: YourVtpassEmail
Password: YourPassword
Please create your authentication details by following the instructions here.
Available Endpoints
To integrate the VTpass third party motor insurance RESTful API, the following endpoints apply:
GET VARIATION CODES
Using a GET method, the VTpass variation codes for third party insurance plans can be accessed with the endpoint below:
Live: https://vtpass.com/api/service-variations?serviceID=ui-insure
Sandbox: https://sandbox.vtpass.com/api/service-variations?serviceID=ui-insure
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{
"response_description": "000",
"content": {
"ServiceName": "Third Party Motor Insurance - Universal Insurance",
"serviceID": "ui-insure",
"convinience_fee": "N0",
"variations": [
{
"variation_code": "1",
"name": "Private",
"variation_amount": "3000.00",
"fixedPrice": "Yes"
},
{
"variation_code": "2",
"name": "Commercial",
"variation_amount": "5000.00",
"fixedPrice": "Yes"
},
{
"variation_code": "3",
"name": "Tricycles",
"variation_amount": "1500.00",
"fixedPrice": "Yes"
},
{
"variation_code": "4",
"name": "Motorcycle",
"variation_amount": "3000.00",
"fixedPrice": "Yes"
}
],
"varations": [
{
"variation_code": "1",
"name": "Private",
"variation_amount": "3000.00",
"fixedPrice": "Yes"
},
{
"variation_code": "2",
"name": "Commercial",
"variation_amount": "5000.00",
"fixedPrice": "Yes"
},
{
"variation_code": "3",
"name": "Tricycles",
"variation_amount": "1500.00",
"fixedPrice": "Yes"
},
{
"variation_code": "4",
"name": "Motorcycle",
"variation_amount": "3000.00",
"fixedPrice": "Yes"
}
]
}
}
GET VEHICLE COLOR CODES
Using a GET method, vehicle color codes can be accessed with the endpoint below:
Live: https://vtpass.com/api/universal-insurance/options/color
Sandbox: https://sandbox.vtpass.com/api/universal-insurance/options/color
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{
"response_description":"000",
"content":[
{
"ColourCode": "20",
"ColourName": "Ash"
},
{
"ColourCode": "1004",
"ColourName": "Black"
},
...
]
}
GET ENGINE CAPACITY CODES
Using a GET method, engine capacity codes can be accessed with the endpoint below:
Live: https://vtpass.com/api/universal-insurance/options/engine-capacity
Sandbox: https://sandbox.vtpass.com/api/universal-insurance/options/engine-capacity
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{
"response_description":"000",
"content":[
{
"CapacityCode": "1",
"CapacityName": "0.1 - 1.59"
},
{
"CapacityCode": "2",
"CapacityName": "1.6 - 2.0"
},
...
]
}
GET STATE CODES
Using a GET method, state codes can be accessed with the endpoint below:
Live: https://vtpass.com/api/universal-insurance/options/state
Sandbox: https://sandbox.vtpass.com/api/universal-insurance/options/state
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{
"response_description":"000",
"content":[
{
"StateCode": "1",
"StateName": "Abia"
},
{
"StateCode": "2",
"StateName": "Adamawa"
},
...
]
}
GET LOCAL GOVERNMENT AREA CODES
Using a GET method, LGA codes can be accessed with the endpoint below:
Live: https://vtpass.com/api/universal-insurance/options/lga/{StateCode}
Sandbox: https://sandbox.vtpass.com/api/universal-insurance/options/lga/{StateCode}
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{
"response_description":"000",
"content":[
{
"LGACode": "770",
"LGAName": "Aba",
"StateCode": "1"
},
{
"LGACode": "1",
"LGAName": "Aba North",
"StateCode": "1"
},
...
]
}
VEHICLE MAKE CODES
Using a GET method, Vehicle make codes can be accessed with the endpoint below:
Live: https://vtpass.com/api/universal-insurance/options/brand
Sandbox: https://sandbox.vtpass.com/api/universal-insurance/options/brand
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{
"response_description":"000",
"content":[
{
"VehicleMakeCode": "335",
"VehicleMakeName": "Ac Cobra"
},
{
"VehicleMakeCode": "1",
"VehicleMakeName": "Acura"
},
...
]
}
VEHICLE MODEL CODES
Using a GET method, Vehicle model codes can be accessed with the endpoint below:
Live: https://vtpass.com/api/universal-insurance/options/model/{VehicleMakeCode}
Sandbox: https://sandbox.vtpass.com/api/universal-insurance/options/model/{VehicleMakeCode}
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{
"response_description":"000",
"content":[
{
VehicleModelCode": "745",
"VehicleModelName": "3.2TL",
"VehicleMakeCode": "1"
},
{
"VehicleModelCode": "1",
"VehicleModelName": "CL",
"VehicleMakeCode": "1"
},
...
]
}
PURCHASE PRODUCT
Using a POST method, third party motor insurance can be purchased with the endpoint below:
Live: https://vtpass.com/api/pay
Sandbox: https://sandbox.vtpass.com/api/pay
ServiceID: ui-insure
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| request_id | M | String | This is a unique reference with which you can use to identify and query the status of a given transaction after the transaction has been executed. |
| serviceID | M | String | Service ID as specified by VTpass. In this case, it is ui-insure |
| billersCode | M | String | The plate Number of the vehicle you wish to make the insurance payment on. In this case: ATU480ER |
| variation_code | M | String | The code of the variation (as specified in the GET VARIATIONS method as variation_code). |
| amount | O | Number | The amount of the variation (as specified in the GET VARIATIONS endpoint as variation_amount)
This amount will be ignored as the variation code determine the price of the data bundle. |
| phone | M | Number | The phone number of the customer or recipient of this service |
| Insured_Name | M | String | Name of the owner of the insured vehicle |
| engine_capacity | M | String | CapacityCode obtained from the get Engine Capacity codes endpoint |
| Chasis_Number | M | String | Chasis Number of the insured vehicle |
| Plate_Number | M | String | Same as the billersCode above |
| vehicle_make | M | String | VehicleMakeCode of the vehicle obtained from the Vehicle Brand endpoint |
| vehicle_color | M | String | ColourCode obtained from the get vehicle color code endpoint |
| vehicle_model | M | String | VehicleModelCode obtained from the get vehicle model endpoint |
| YearofMake | M | String | The year the insured vehicle was made. |
| state | M | String | The StateCode obtained from the get state codes endpoint. |
| lga | M | String | The StateCode obtained from the get state codes endpoint. |
| M | String | Email address of the customer |
SAMPLE REQUEST
{
"request_id":"2023050316471112",
"serviceID":"ui-insure",
"variation_code":1,
"phone":"08111111111",
"Insured_Name":"Mr Ajanlekoko",
"engine_capacity":1,
"Chasis_Number":"S12332323FRHJJ433434J",
"Plate_Number":"ATU480ER",
"billersCode":"ATU480ER",
"vehicle_make":335,
"vehicle_color":20,
"vehicle_model":745,
"YearofMake":2009,
"state":1,
"lga":770,
"email":"sandbox@vtpass.com"
}
EXPECTED RESPONSE
{
"code": "000",
"content": {
"transactions": {
"status": "delivered",
"product_name": "Third Party Motor Insurance - Universal Insurance",
"unique_element": "ATU480ER",
"unit_price": "3000",
"quantity": 1,
"service_verification": null,
"channel": "api",
"commission": 3000,
"total_amount": 27000,
"discount": null,
"type": "Insurance",
"email": "sandbox@sandbox.vtpass.com",
"phone": "123450987623",
"name": null,
"convinience_fee": 0,
"amount": "3000",
"platform": "api",
"method": "api",
"transactionId": "17398729734891902716575111",
"commission_details": { "amount": 10.22, "rate": "1.50", "rate_type": "percent", "computation_type": "default" },
}
},
"response_description": "TRANSACTION SUCCESSFUL",
"requestId": "2025021811026IMK9CF1",
"amount": 3000,
"transaction_date": "2025-02-18T10:02:53.000000Z",
"purchased_code": "Download Certificate : https://3rdparty.universalinsuranceonline.com/PrintCertificate.aspx?Data=UPMSB001310125D949061969202",
"certUrl": "https://3rdparty.universalinsuranceonline.com/PrintCertificate.aspx?Data=UPMSB001310125D949061969202"
}
QUERY TRANSACTION STATUS
Using a POST method, transaction status can be queried with the endpoint below:
Live: https://vtpass.com/api/requery
Sandbox: https://sandbox.vtpass.com/api/requery
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| request_id | M | String |
This is the reference with which you sent when purchasing a transaction after the transaction has been executed. |
EXPECTED RESPONSE
{
"code": "000",
"content": {
"transactions": {
"status": "delivered",
"product_name": "Third Party Motor Insurance - Universal Insurance",
"unique_element": "ATU480ER",
"unit_price": 3000,
"quantity": 1,
"service_verification": null,
"channel": "api",
"commission": 3000,
"total_amount": 27000,
"discount": null,
"type": "Insurance",
"email": "sandbox@vtpass.com",
"phone": "07061933309",
"name": null,
"convinience_fee": 0,
"amount": "3000.00",
"platform": "api",
"method": "wallet",
"transactionId": "1582531685722",
"commission_details": { "amount": 10.22, "rate": "1.50", "rate_type": "percent", "computation_type": "default" },
}
},
"response_description": "TRANSACTION SUCCESSFUL",
"requestId": "3476we12jaja7jjd",
"amount": "3000.00",
"transaction_date": {
"date": "2020-02-24 09:08:05.000000",
"timezone_type": 3,
"timezone": "Africa/Lagos"
},
"purchased_code": "Download Certificate : https://3rdparty.universalinsuranceonline.com/PrintCertificate.aspx?Data=UPMSB001190319136038",
"certUrl": "https://3rdparty.universalinsuranceonline.com/PrintCertificate.aspx?Data=UPMSB001190319136038"
}
You can check out the complete list of RESPONSE CODES HERE.