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.

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 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).
email 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.