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 the mobile network operator (telco) and by country.

With these limitations in mind, we wanted to make this API super easy to use. We didn’t want you to worry about what mobile network operator a phone number is on for you to be able to easily send prepaid airtime to the phone number.  So to simplify things, we created our Airtime Top-Up API with two parameters: the maxAmount parameter and the desiredAmount parameter.

maxAmount Parameter

In the maxAmount 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 20 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.

desiredAmount Parameter

The desiredAmount parameter, which is optional but recommended, flips the perspective of the API.  By passing a desiredAmount, you can specify the top-up amount you prefer to send to the phone number.

If the desiredAmount is available for the phone number, then we will send that amount.  If it is not available, then we will send the next amount higher that is available, but no higher than the maxAmount.

For example, if you pass a phone number on the Smart network in the Philippines, a desiredAmount of 20, and a maxAmount of 30, then we’ll send 20 pesos to that phone number because that’s an available amount for mobile phones on the Smart network. But if you pass a phone number on the Globe network in the Philippines with the same desiredAmount and maxAmount parameters, we’ll send 25 pesos to that phone number because that’s the closest amount available that is greater than or equal to the desiredAmount of 20 and less than or equal to the maxAmount of 30 for mobile phones on the Globe network. As mentioned above, you can refer to our pricing table to see the available amounts.

Currencies

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.  Moreover, in countries where we can send in local currency, there are some circumstances where a slightly higher amount will be sent than what you specify, but you will still be charged what is listed in our pricing table for the amount you specify.  Once again, please refer to our pricing table to see the currencies and amounts available per telco per country.

HTTP Method & Headers

The HTTP method is POST using this URL:

https://api.engagespark.com/v1/organizations/{ORGID}/topup/

Replace {ORGID} with your actual organization ID from your account. Find it in your organization profile: https://app.engagespark.com/account/organization/info

 

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://app.engagespark.com/account/profile/info).

 

Parameters:

{
    "fullPhoneNumber": "629123456789",
    "maxAmount": "10000",
    "desiredAmount": "1000",
    "clientRef": "12345abc"
}

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	629123456789
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	10000
desiredAmount	Desired 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 greater than or equal to the desiredAmount but no higher than the maxAmount . Please reference the pricing table for available amounts.	String	Optional	1000
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

Sample Successful and Failed Transaction Results:

Successful Transaction

{
    "id": "12345",
    "maxAmount": 10000,
    "desiredAmount": 1000,
    "fullPhoneNumber": "629123456789",
    "contactId": 1234567890,
    "clientRef": "12345abc",
    "currency": "IDR",
    "amountSent": 5000,
    "price": 0.55,
    "createdDate": "2021-04-16T18:53:44.979304527Z",
    "error": ""
}

Failed Transactions

{
    "error": "no matching product found"
}

{
    "error": "invalid phone number"
}

Response Body Definition

Key	Description	Example
id	engageSPARK system-generated unique transaction ID.	“12345”
maxAmount	The max airtime amount you specified in your request.	10000
desiredAmount	The desired airtime amount you specified in your request.	1000
fullPhoneNumber	The mobile phone number where you want the airtime top-up to be sent.	“629123456789”
contactId	engageSPARK system-generated unique ID for every phone number passing through the system.	1234567890
clientRef	The reference number or id you specified in your request.	“12345abc”
currency	The currency used for the airtime top-up request.	“IDR”
amountSent	The exact amount sent to the phone number.	5000
price	This is how much engageSPARK charged you for the airtime top-up request.	0.55
createdDate	The timestamp of when the request was made.	“2021-04-16T18:53:44.979304527Z”
error	This is where you will see the error message if there is an error in your request.	“no matching product found”

 

Retries – Very Important

One very important feature of this API is that it has built-in automated retries. This means that in any instances that your airtime top-up request fails, our system retries it 6x within 4-5 hours:

1st retry: scheduled 1 minute after the initial request

2nd retry: scheduled 2 minutes after the previous request

3rd retry: scheduled 5 minutes after the previous request

4th retry: scheduled 30 minutes after the previous request

5th retry: scheduled 60 minutes after the previous request

6th retry: scheduled 120 minutes after the previous request

 

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

Click to View – Airtime Top-up Global Pricing