Airtime Top Up API (Global)

With the engageSPARK Airtime Top Up API, you can send prepaid airtime to anyone on the fly! In some countries, airtime is known as prepaid phone credit or mobile credit or load top up.

We are able to send very specific amounts of airtime per mobile network operator in each country.  For example, we cannot send 25 Philippine pesos of airtime to a mobile phone on the Smart mobile network in the Philippines, but we can send 25 pesos to a mobile phone on the Globe mobile network. The amounts available differ by mobile network operator (telco) and by country.

maxAmount Parameter

With that in mind, we wanted to make this API super easy to use. We didn’t want you to have to know what mobile network operator a phone number is on for you to be able to easily send prepaid airtime to the phone number.  So, we created our Airtime Top Up API with a maxAmount parameter.  For this parameter, you specify the maximum amount you want to send to the phone number.  If that amount is available, we’ll send that amount; if it’s not available, then we’ll send the closest amount available that is smaller than the maxAmount you specified.

For example, if you pass a phone number on the Globe network in the Philippines and a maxAmount of 25, we’ll send 25 pesos to that phone number because that’s an available amount for mobile phones on the Globe network.  But if you pass a phone number on the Smart network in the Philippines and a maxAmount of 25, we’ll send that phone number 15 pesos of airtime because that’s the closest amount available that is smaller than 25. Please refer to our pricing table to see the available amounts.

Please also note that for most countries, we are able to send airtime in local currency; in some countries, we can send airtime only in USD. The recipient will receive the airtime in their local currency, but the conversion from USD to the local currency will happen at the time of the transfer, so the received amount may be slightly different each time depending on exchange rates.

HTTP Method & Headers

The HTTP method is POST using this URL:

https://api.engagespark.com/v1/airtime-topup

You’ll need to set the following HTTP Headers:

Key Value
Authorization Token {API_KEY}
Content-type application/json

Replace {API_KEY} with your actual API Key from your account. Find it in your profile under Account Settings > API Key (https://ui.engagespark.com/#/api/docs).

Please note that this is an asynchronous API.  You will always get a 200 when you post to this API. All error messages will be sent to the URL endpoint (resultsUrl parameter) that you specify in your API request.

Parameters

{

 

phoneNumber”: “639123456789”,

 

organizationId”: “123”,

 

maxAmount”: “15”,

 

clientRef”: “12345abc”,

 

resultsUrl”: “https://www.example.com”

 

}

Request Body Definition

Key Description Data Type Required Example
phoneNumber The mobile number you want to send the airtime top up to. The phone number must be in international format (with country code e.g., 63). Please do not include a + sign. String Yes 639123456789
organizationId The organization id of the account sending the airtime.  Find it in your organization profile: https://ui.engagespark.com/#/organizations/details String Yes 123
maxAmount Max airtime amount you want to send. Please see the introduction above for a detailed explanation.  In brief, we will send this amount if it’s available; if not, we’ll send the closest amount available that is smaller than this amount. Please reference the pricing table for available amounts. String Yes 15
clientRef The reference number or id you want to assign to your airtime top up transaction. This is typically an ID unique to each request so that you can easily identify the request when we send you the result. String Optional 12345abc
resultsUrl Your server URL / endpoint where we should forward the result of your airtime top up request. This also is where we will send all error messages because the Airtime Top Up API is an asynchronous API. String Optional, but highly recommended https://www.example.com

Sample Successful and Failed Transaction Results

{

 

phoneNumber” : “639123456789”,

 

maxAmount” : “25”,

 

amountSent” : “15”,

 

price” : “0.388”,

 

status”: “Success”,

 

errorMesage” : “The value was successfully delivered to the recipient.”,

 

clientRef” : “12345abc”,

 

createdDate” : “2018-06-28 20:59:54”

 

}

{

 

phoneNumber”: “639003456789”,

 

maxAmount” : “25”,

 

amountSent”: “15”,

 

price”: “0.388”,

 

status”: “Failed”,

 

errorMesage”: “The phone number of the recipient is not a valid prepaid number.”,

 

clientRef”: “12345abc”,

 

createdDate”: “2018-06-28 21:03:57”

 

}

Click to Download – Airtime Top-up Error Codes and Messages

Click to View – Airtime Top-up Global Pricing

Have questions or need a little extra help?

Get in touch with us via:

Or drop us a message here: