Health Insurance API

This section contains the recommended flow for integrating health 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 health insurance RESTful API, the endpoints below applies:

  • Get Variation Codes (endpoint to get the various health plans available).
  • Get Extra fields (endpoint to get the fields required for this product purchase such as full_name, selected_hospital).
  • Get Options (endpoint to get the option for some fields required to purchase this product. For instance selected_hospital has various options).
  • Purchase Product (Using the variation code, extra_fields and options gotten in the first, second and third step).
  • Query transaction status

 

GET VARIATION CODES

Using a GET method, the VTpass variation codes for health insurance plans can be accessed with the endpoint below:

Live:   https://api-service.vtpass.com/api/service-variations?serviceID=health-insurance-rhl

Sandbox: https://sandbox.vtpass.com/api/service-variations?serviceID=health-insurance-rhl

FIELDS Mandatory/Optional TYPE DESCRIPTION
N/A N/A N/A N/A

 

EXPECTED RESPONSE

{
    "response_description": "000",
    "content": {
        "ServiceName": "Health Insurance - HMO  ",
        "serviceID": "health-insurance-rhl",
        "convinience_fee": "0 %",
        "varations": [
            {
                "variation_code": "individual-monthly",
                "name": "Individual (One person) - Monthly - 2,000 Naira",
                "variation_amount": "2000.00",
                "fixedPrice": "Yes"
            },
            {
                "variation_code": "individual-annual",
                "name": "Individual (One Person) - Annual 15,000 Naira",
                "variation_amount": "15000.00",
                "fixedPrice": "Yes"
            },
            ...
       ]
   }
}

GET EXTRA FIELDS

Using a GET method, the VTpass extra fields for health insurance plans can be accessed with the endpoint below:

Live:   https://api-service.vtpass.com/api/extra-fields?serviceID=health-insurance-rhl

Sandbox: https://sandbox.vtpass.com/api/extra-fields?serviceID=health-insurance-rhl

FIELDS Mandatory/Optional TYPE DESCRIPTION
N/A N/A N/A N/A

 

EXPECTED RESPONSE

{
    "response_description": "000",
    "ServiceName": "Health Insurance - HMO  ",
    "serviceID": "health-insurance-rhl",
    "content": [
        {
            "optionName": "full_name",
            "optionType": "TextInput",
            "optionLabel": "Full Name",
            "optionRule": ""
        },
        {
            "optionName": "address",
            "optionType": "TextInput",
            "optionLabel": "Home Address",
            "optionRule": ""
        },
        ...
      ]
   }
}

GET OPTIONS

Using a GET method, the VTpass options for health insurance plans can be accessed with the endpoint below:

Live:   https://api-service.vtpass.com/api/options?serviceID=health-insurance-rhl&name=selected_hospital

Sandbox: https://sandbox.vtpass.com/api/options?serviceID=health-insurance-rhl&name=selected_hospital

FIELDS Mandatory/Optional TYPE DESCRIPTION
serviceID N/A string Service ID as specified by VTpass. In this case, it is health-insurance
name N/A string Name as specified by VTpass https://sandbox.vtpass.com/api/extra-fields?serviceID=health-insurance-rhl endpoint. In this case, it is selected_hospital

 

EXPECTED RESPONSE

{
    "response_description": "000",
    "content": {
        "ServiceName": "Health Insurance - HMO  ",
        "serviceID": "health-insurance-rhl",
        "optionName": "selected_hospital",
        "optionType": "Select",
        "optionLabel": "Selected Hospital",
        "optionRule": "",
        "options": {
            "abia": {
                "aba": {
                    "life_care_clinics": "Life Care Clinics (8, Eziukwu Road), Aba, Abia",
                    "the_blessed_haven_hospital": "The Blessed Haven Hospital (50 Omoba Road Ogbor Hill), Aba, Abia"
                },
                "arochukwu": {
                    "mercy_catholic_hospital": "Mercy Catholic Hospital (Ihechioma), Arochukwu, Abia"
                },
                "ohafia": {
                    "uzondu_polyclinic": "Uzondu Polyclinic (No 8, Ofali Agwi Road, Amaekpu), Ohafia, Abia"
                },
                "umuahia": {
                    "new_era_hospital": "New Era Hospital (90b, Oji River Street Amuzukwu Layout), Umuahia, Abia",
                    "hammersmith_medical_centre": "Hammersmith Medical Centre (Block 3, Amuzukwu Road), Umuahia, Abia",
                    "the_lords_foundation_clinic": "The Lords Foundation Clinic (No 5a, Hill Top Road Ugwunchara), Umuahia, Abia"
                }
            },
            "adamawa": {
                "mubi": {
                    "newlife_hospital,_mubi": "Newlife Hospital, Mubi (3, Lokuwa Ward), Mubi, Adamawa"
                },
                "yola": {
                    "federal_medical_centre": "Federal Medical Centre (Lamido Zubairu Road), Yola, Adamawa",
                    "gal-bose_hospital": "Gal-bose Hospital (Lamido Zubairu Road), Yola, Adamawa",
                    "matco_clinic": "Matco Clinic (Lamido Zubairu Road), Yola, Adamawa",
                    "adamawa_hospital_limited": "Adamawa Hospital Limited (2, Lamido Sanda Road), Yola, Adamawa"
                }
            },
            ...
      ]
   }
}

PURCHASE PRODUCT

Using a POST method, health insurance can be purchased with the endpoint below:

 

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

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

ServiceID: health-insurance-rhl

 

 

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 health-insurance-rhl
billersCode M String The Full name of the person you wish to make the insurance payment on. In this case: Testimetri Adams
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
full_name M String The Full name of the person you wish to make the insurance payment on.
address M String The Address of the person you wish to make the insurance payment on.
selected_hospital M String The selected option gotten from GET OPTIONS API. 

Note: The array key is the name of the hospital.
Passport_Photo M String The passport photo of the person in base64 format.
date_of_birth M String The date of birth of the person insured in form of YYYY-mm-dd.
extra_info M String A remark.

 

EXPECTED RESPONSE

{
    "code": "000",
    "content": {
        "transactions": {
            "status": "delivered",
            "product_name": "Health Insurance - HMO  ",
            "unique_element": "Testimetri Adams",
            "unit_price": 2000,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 100,
            "total_amount": 2000,
            "discount": null,
            "type": "Insurance",
            "email": "sandbox@vtpass.com",
            "phone": "07061933309",
            "name": null,
            "convinience_fee": 100,
            "amount": 2000,
            "platform": "api",
            "method": "api",
            "transactionId": "1600876357998"
        }
    },
    "response_description": "TRANSACTION SUCCESSFUL",
    "requestId": "34uiejpj7ui9i0sd09h4j9imddrt0yu",
    "amount": "2000.00",
    "transaction_date": {
        "date": "2020-09-23 16:52:37.000000",
        "timezone_type": 3,
        "timezone": "Africa/Lagos"
    },
    "purchased_code": ""
}

 

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": "Health Insurance - HMO  ",
            "unique_element": "Testimetri Adams",
            "unit_price": 2000,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 100,
            "total_amount": 2000,
            "discount": null,
            "type": "Insurance",
            "email": "sandbox@vtpass.com",
            "phone": "07061933309",
            "name": null,
            "convinience_fee": 100,
            "amount": "2000.00",
            "platform": "api",
            "method": "wallet",
            "transactionId": "1601024046923"
        }
    },
    "response_description": "TRANSACTION SUCCESSFUL",
    "requestId": "34uiejp7ui9i0sdd0h9jhj4j9imddrt0yu",
    "amount": "2000.00",
    "transaction_date": {
        "date": "2020-09-25 09:54:06.000000",
        "timezone_type": 3,
        "timezone": "Africa/Lagos"
    },
    "purchased_code": ""
}

 
You can check out the complete list of RESPONSE CODES HERE.

 

 

Home Cover Insurance API

This section contains the recommended flow for integrating home cover 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 home cover insurance RESTful API, the endpoints below applies:

  • Get Variation Codes (this endpoint returns variation codes for various home cover insurance plans).
  • Get Extra fields (this endpoint gets all the extra field names required to purchase this product for instance full_name).
  • Get Options for various home cover extra field. (this endpoint gets all the options for a specific field required in purchasing this product).
  • 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 home cover insurance plans can be accessed with the endpoint below:

Live:   https://api-service.vtpass.com/api/service-variations?serviceID=home-cover-insurance

Sandbox: https://sandbox.vtpass.com/api/service-variations?serviceID=home-cover-insurance

FIELDS Mandatory/Optional TYPE DESCRIPTION
N/A N/A N/A N/A

 

EXPECTED RESPONSE

{
    "response_description": "000",
    "content": {
        "ServiceName": "Home Cover Insurance",
        "serviceID": "home-cover-insurance",
        "convinience_fee": "0 %",
        "varations": [
            {
                "variation_code": "option-a",
                "name": "Option A - 7,500 Naira yearly",
                "variation_amount": "7500.00",
                "fixedPrice": "Yes"
            },
            {
                "variation_code": "option-b",
                "name": "Option B - 15,000 Naira yearly",
                "variation_amount": "15000.00",
                "fixedPrice": "Yes"
            },
            ...
       ]
    }
}

 

GET EXTRA FIELDS

Using a GET method, the VTpass extra fields for home cover insurance plans can be accessed with the endpoint below:

Live:   https://api-service.vtpass.com/api/extra-fields?serviceID=home-cover-insurance

Sandbox: https://sandbox.vtpass.com/api/extra-fields?serviceID=home-cover-insurance

FIELDS Mandatory/Optional TYPE DESCRIPTION
N/A N/A N/A N/A

 

EXPECTED RESPONSE

{
    "response_description": "000",
    "ServiceName": "Home Cover Insurance",
    "serviceID": "home-cover-insurance",
    "content": [
        {
            "optionName": "full_name",
            "optionType": "TextInput",
            "optionLabel": "Full Name",
            "optionRule": ""
        },
        {
            "optionName": "address",
            "optionType": "TextInput",
            "optionLabel": "Address of insured property ",
            "optionRule": ""
        },
        {
            "optionName": "type_building",
            "optionType": "Select",
            "optionLabel": "Type of Building",
            "optionRule": ""
        },
        ...

GET OPTIONS

Using a GET method, the VTpass options for home cover insurance plans can be accessed with the endpoint below:

Live:   https://api-service.vtpass.com/api/options?serviceID=home-cover-insurance&name=type_building

Sandbox: https://sandbox.vtpass.com/api/options?serviceID=home-cover-insurance&name=type_building

FIELDS Mandatory/Optional TYPE DESCRIPTION
serviceID N/A string Service ID as specified by VTpass. In this case, it is home-cover-insurance
name N/A string Name as specified by VTpass https://sandbox.vtpass.com/api/extra-fields?serviceID=health-insurance-rhl endpoint. In this case, it is type_building

 

EXPECTED RESPONSE

{
    "response_description": "000",
    "content": {
        "ServiceName": "Home Cover Insurance",
        "serviceID": "home-cover-insurance",
        "optionName": "type_building",
        "optionType": "Select",
        "optionLabel": "Type of Building",
        "optionRule": "",
        "options": {
            "bungalow": "Bungalow",
            "duplex": "Duplex",
            "flat": "Flat",
            "others": "Others"
        }
    }
}

PURCHASE PRODUCT

Using a POST method, home cover insurance can be purchased with the endpoint below:

 

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

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

ServiceID: home-cover-insurance

 

 

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 home-cover-insurance
billersCode M String The Full name of the person you wish to make the insurance payment on. In this case: Testimetri Adams
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 plan.
phone M Number The phone number of the customer or recipient of this service
full_name M String The Full name of the person you wish to make the insurance payment on.
address M String The Address of the person you wish to make the insurance payment on.
type_building M String The selected option gotten from GET OPTIONS API. 

Note: The array key for the type of supported building. For instance “duplex”
business_occupation M String The customer’s occupation.
date_of_birth M String The date of birth of the person insured in form of YYYY-mm-dd.

 

EXPECTED RESPONSE

{
    "code": "000",
    "content": {
        "transactions": {
            "status": "delivered",
            "product_name": "Home Cover Insurance",
            "unique_element": "Testimetri Adams",
            "unit_price": 7500,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 100,
            "total_amount": 7400,
            "discount": null,
            "type": "Insurance",
            "email": "sandbox@vtpass.com",
            "phone": "07061933309",
            "name": null,
            "convinience_fee": 0,
            "amount": 7500,
            "platform": "wallet",
            "method": "api",
            "transactionId": "1601026769134"
        }
    },
    "response_description": "TRANSACTION SUCCESSFUL",
    "requestId": "34judj9ksjkdjh4j9imdfdrt0yu",
    "amount": "7500.00",
    "transaction_date": {
        "date": "2020-09-25 10:39:29.000000",
        "timezone_type": 3,
        "timezone": "Africa/Lagos"
    },
    "purchased_code": ""
}

 

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": "Home Cover Insurance",
            "unique_element": "Testimetri Adams",
            "unit_price": 7500,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 100,
            "total_amount": 7400,
            "discount": null,
            "type": "Insurance",
            "email": "sandbox@vtpass.com",
            "phone": "07061933309",
            "name": null,
            "convinience_fee": 0,
            "amount": "7500.00",
            "platform": "wallet",
            "method": "wallet",
            "transactionId": "1601026769134"
        }
    },
    "response_description": "TRANSACTION SUCCESSFUL",
    "requestId": "34judj9ksjkdjh4j9imdfdrt0yu",
    "amount": "7500.00",
    "transaction_date": {
        "date": "2020-09-25 10:39:29.000000",
        "timezone_type": 3,
        "timezone": "Africa/Lagos"
    },
    "purchased_code": ""
}

 
You can check out the complete list of RESPONSE CODES HERE.