International Airtime/Data/Pin API
This section contains the recommended flow for integrating International Airtime/Data/Pin services on the VTpass RESTful API.
Authentication
Learn about authentication from here.
Available Endpoints
To integrate the VTpass International Airtime/Data/Pin Payment RESTful API, the endpoints below applies:
- Get International Airtime Countries: this returns the various countries you can purchase for.
- Get International Airtime Product Types: this returns the various types of product that can be purchased
- Get International Airtime Operators: this returns the various service providers/operators you can purchase for.
- Get Variation Codes: this returns variation codes for various International Airtime Operators
- Purchase Product (Using the variation code gotten in the first step)
- Query transaction status
GET International Airtime Countries
Using a GET method, the VTpass countries for International Airtime/Data/Pin can be accessed with the endpoint below:
Live: https://vtpass.com/api/get-international-airtime-countries
Sandbox: https://sandbox.vtpass.com/api/get-international-airtime-countries
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{ "response_description": "000", "content": { "countries": [ { "code": "CM", "flag": "https://sandbox.vtpass.com/resources/images/flags/CM.png", "name": "Cameroon", "currency": "XAF", "prefix": "237" }, { "code": "GH", "flag": "https://sandbox.vtpass.com/resources/images/flags/GH.png", "name": "Ghana", "currency": "GHS", "prefix": "233" }, ..... ] } }
GET International Airtime Product Types
Using a GET method, the VTpass countries for International Airtime/Data/Pin Product Types can be accessed with the endpoint below; The code is the Country code (as specified in the GET International Airtime Countries method as code).
Live: https://vtpass.com/api/get-international-airtime-product-types?code=GH
Sandbox: https://sandbox.vtpass.com/api/get-international-airtime-product-types?code=GH
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{ "response_description": "000", "content": [ { "product_type_id": 4, "name": "Mobile Data" }, { "product_type_id": 1, "name": "Mobile Top Up" } ] }
GET International Airtime Operators
Using a GET method, the VTpass countries for International Airtime/Data/Pin Operators can be accessed with the endpoint below; The code is the Country code (as specified in the GET International Airtime Countries method as code). The product_type_id is the Product Type ID (as specified in the Get International Airtime Product Types method as product_type_id)
Live: https://vtpass.com/api/get-international-airtime-operators?code=GH&product_type_id=4
Sandbox: https://sandbox.vtpass.com/api/get-international-airtime-operators?code=GH&product_type_id=4
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{ "response_description": "000", "content": [ { "operator_id": "5", "name": "Ghana MTN", "operator_image": "https://sandbox.vtpass.com/resources/images/operators/80.png", } ] }
GET VARIATION CODES
Using a GET method, the VTpass variation codes for International Airtime/Data/Pin can be accessed with the endpoint below; operator_id is the OPERATOR ID (as specified in the GET International Airtime Operators method as operator_id). The product_type_id is the Product Type ID (as specified in the Get International Airtime Product Types method as product_type_id).
Live: https://vtpass.com/api/service-variations?serviceID=foreign-airtime&operator_id=1&product_type_id=1
Sandbox: https://sandbox.vtpass.com/api/service-variations?serviceID=foreign-airtime&operator_id=1&product_type_id=1
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
N/A | N/A | N/A | N/A |
Note: The charged amount is the amount VTpass charges your wallet. For variations with the fixed price is the charged_amount (naira equivalent). For variations with the flexible price the charged amount (naira equivalent) can be calculated using variation_rate * amount in GHS.
EXPECTED RESPONSE
{ "response_description": "000", "content": { "ServiceName": "Foreign Airtime", "serviceID": "foreign-airtime", "convinience_fee": "0 %", "currency": "GHS", "variations": [ { "variation_code": "5", "name": "Enter flexible amount", "fixedPrice": "No", "variation_amount": null, "variation_amount_min": 1, "variation_amount_max": 120, "variation_rate": 71.58, "charged_amount": null, "charged_currency": "NGN" } ], "varations": [ { "variation_code": "5", "name": "Enter flexible amount", "fixedPrice": "No", "variation_amount": null, "variation_amount_min": 1, "variation_amount_max": 120, "variation_rate": 71.58, "charged_amount": null, "charged_currency": "NGN" } ] } }
PURCHASE PRODUCT
Using a POST method, International Airtime/Data/Pin can with the endpoint below:
Live: https://vtpass.com/api/pay
Sandbox: https://sandbox.vtpass.com/api/pay
ServiceID: foreign-airtime
On sandbox, use test phone number: 08011111111
To simulate a failed transaction on sandbox, please use any number apart from the one provided above as the phone number.
Note: For VTU pins instructions on how to recharge will be in the response object
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 foreign-airtime |
billersCode | M | String | The phone number you wish to make the Subscription payment on |
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 |
operator_id | M | String | The ID of the operator (as specified in the GET International Airtime Operators method as operator_id). |
country_code | M | String | The code of the country (as specified in the GET International Airtime Countries method as code). |
product_type_id | M | String | The Id of the Product Type of International Aitime/Data/Pin (as specified in the Get International Airtime Product Types method as product_type_id). |
M | String | The email address of the customer. |
EXPECTED RESPONSE
{ "code": "000", "content": { "transactions": { "status": "delivered", "product_name": "Foreign Airtime", "unique_element": "2348011111111", "unit_price": 1300, "quantity": 1, "service_verification": null, "channel": "api", "commission": 0, "total_amount": 1400, "discount": null, "type": "Airtime Recharge", "email": "sandbox@vtpass.com", "phone": "07061933309", "name": null, "convinience_fee": 100, "amount": 1300, "platform": "api", "method": "api", "transactionId": "16493439915752685306221684" } }, "response_description": "TRANSACTION SUCCESSFUL", "requestId": "202204071606ksemeoqykrmtisffmfkd45jkfdjdjjeodlkuwokdckfjf", "amount": "1300.00", "transaction_date": { "date": "2022-04-07 16:06:31.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://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": "Foreign Airtime", "unique_element": "2348011111111", "unit_price": 1300, "quantity": 1, "service_verification": null, "channel": "api", "commission": 0, "total_amount": 1400, "discount": null, "type": "Airtime Recharge", "email": "sandbox@vtpass.com", "phone": "07061933309", "name": null, "convinience_fee": 100, "amount": 1300, "platform": "api", "method": "api", "transactionId": "16493439915752685306221684" } }, "response_description": "TRANSACTION SUCCESSFUL", "requestId": "202204071606ksemeoqykrmtisffmfkd45jkfdjdjjeodlkuwokdckfjf", "amount": "1300.00", "transaction_date": { "date": "2022-04-07 16:06:31.000000", "timezone_type": 3, "timezone": "Africa/Lagos" }, "purchased_code": "" }
You can check out the complete list of RESPONSE CODES HERE.