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 endpoints below applies:

  • Get Variation Codes: this returns variation codes for various third party insurance plans
  • Purchase Product (Using the variation code gotten in the first step)
  • Query transaction status

 

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://api-service.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.00",
      "varations":[  
          {
                "variation_code": "1",
                "name": "Private",
                "variation_amount": "3000.00",
                "fixedPrice": "Yes"
          },
          ...
      ]
   }
}

PURCHASE PRODUCT

Using a POST method, third party motor insurance can be purchased with the endpoint below:

 

Live: https://api-service.vtpass.com/api/pay

Sandbox: https://sandbox.vtpass.com/api/pay

ServiceID: waec-registration

 

 

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.

Click here to understand how to generate a valid request ID
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_Number M String Engine Number of the insured vehicle
Chasis_Number M String Chasis Number of the insured vehicle
Plate_Number M String Same as the billersCode above
Vehicle_Make M String Make of the insured vehicle
Vehicle_Color M String Vehicle color
Vehicle_Model M String Model of the insured vehicle
Year_of_Make M String The year the insured vehicle was made.
Contact_Address M String Contact Address of the vehicle owner

 

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": 30000,
      "total_amount": -27000,
      "discount": null,
      "type": "Insurance",
      "email": "sandbox@vtpass.com",
      "phone": "07061933309",
      "name": null,
      "convinience_fee": 0,
      "amount": 3000,
      "platform": "api",
      "method": "api",
      "transactionId": "1582531685722"
       }
    },
    "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"
}


 


QUERY TRANSACTION STATUS


Using a POST method, transaction status can be queried with the endpoint below:


Live: https://api-service.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": 30000,
            "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"
        }
    },
    "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.