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

Note: For VTU pins instructions on how to recharge will be in the response object

The sandbox environment provides specific scenarios to simulate success, failure, or unexpected outcomes for airtime purchases. Use the examples below to test and observe how your integration behaves.

Refer to the table below to find the correct phone number for simulating various API responses:

Phone Number  Event Description
08011111111 Successful  Returns a successful response for testing airtime purchases.
201000000000 Pending Simulates an unexpected pending response.
500000000000 Unexpected Response Simulates an expected response, used to test how your system handles anomalies.
400000000000 No Response Simulates a scenario where the API returns no response.
300000000000 Timeout Simulates a timeout scenario for testing response handling under delays.
Any random phone number other than the above Failed Simulates a failed scenario for testing error handling for transaction failure.

 

NEEDED PAYLOAD

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.