Send Airtime

You need your AfricasTalking username and APIKey for any request to our API. If you don't have an APIKey, please click here to get one.

The Node.js code snippet below shows how to send airtime using our API.


//Import the required libraries
querystring = require('querystring');
https       = require('https');

var username = "myAfricasTalkingUsername";
var apiKey   = "myAfricasTalkingAPIkey";

//create the send airime function
function sendAirtime(recipients_) {
	//Build post string from object
	
 var post_data = querystring.stringify({
       'username'   : username,
       'recipients' : recipients_
 });
 
 //create the request paramater object
 
 var request_parameters = {
      host    : 'api.africastalking.com',
      port    : 443,
      path    : '/version1/airtime/send',
      
      rejectUnauthorized : false,
      requestCert        : true,
      agent              : false,
      
      method  : 'POST',
      
      headers : {
      	           
	         'Content-Type'   : 'application/x-www-form-urlencoded',
	         'Content-Length' : post_data.length,
	         'apikey'         : apiKey,
	         'Accept'         : 'application/json'
	      }
   }
                         
  request = https.request(request_parameters, function (response) {
     response.setEncoding('utf8');
     response.on('data', function (data_chunk) {
     	 try {
         if(response.statusCode != 201)
            throw data_chunk;

         var jsObject       = JSON.parse(data_chunk);
         var result_details = jsObject.responses;
         var logStr = "";
         for (recipient in result_details) {
           logStr    += "\nStatus => "       + result_details[recipient].status;
           logStr    += ";phone number => "  + result_details[recipient].phoneNumber;
           logStr    += ";amount => "        + result_details[recipient].amount;
           logStr    += ";cost => "          + result_details[recipient].cost;
           logStr    += ";discount => "      + result_details[recipient].discount;
           logStr    += ";error message => " + result_details[recipient].errorMessage;
         }
          console.log(logStr);
        }
        catch (error) {
         console.log("Error: " + error);
        }
     });
  });
  
  request.write(post_data);
  request.end();
}

// Specify an array to hold airtime recipients and amount

var airtime RecipientsList = [];


// Specify the first recipients to a json object and add it to the airtimeRecipientsList
// Please ensure you include the country code for phone numbers (+254 for Kenya in this case)
// Please ensure you include the country code for phone numbers (KES for Kenya in this case)

airtimeRecipientsList[0] = {phoneNumber : '+254711XXXYYY', amount : 'KES XXX'};

// Specify the second recipient
airtimeRecipientsList[1] = {phoneNumber : '+254733YYYZZZ', amount : 'KES YYY'};

// Convert the airtimeRecipientsList to a string
// NB: The expected string format is: [{phoneNumber : '+254711XXXYYY', amount : 'KES XXX'}, {phoneNumber : '+254733YYYZZZ', amount : 'KES YYY'}]
var recipient_string = JSON.stringify(airtimeRecipientsList);

//call the function
sendAirtime(recipient_string);

To send airtime you will need to make a HTTP POST request to the following url:
POST URL: http://api.africastalking.com/version1/airtime/send

Limits

We however have a limit of the amount you can send as shown below:

Minimum amount Maximum amount
KES 10 KES 10,000
The server expects:
Parameter Location Description Required
API key Header API key generated from your account settings Yes
Accept Header This is the format you would like your data formatted. It may be application/xml or application/json. The default is application/xml. The gateway classes provided uses appliaction/json. No
username Body This is your Africa'sTalking username Yes
recipients Body Contains the a list of airtime recipients in JSON format. It should look like:
[{"phoneNumber":"+254711XXXYYY","amount":"KES X"},{"phoneNumber":"+254733YYYZZZ","amount":"KES Y"}]
Yes
Upon successful processing, the server shall respond in the following format:
XML
                        
<?xml version="1.0"?>
  <AirtimeResponse>
    <numSent>n</numSent>
    <totalAmount>KES XXX</totalAmount>
    <totalDiscount>KES YYY</totalDiscount>
    <responses>
      <response>
        <phoneNumber>+254711XXXYYY</phoneNumber>
        <amount>KES 1000.0000</amount>
        <discount>40.0000</discount>
        <status>Success</status>
        <requestId>ATQid_4fbec14b3c6b976d398957f9f8a65b3d</requestId>
        <errorMessage>None</errorMessage>
      </response>
      .
      .
      .
      .
      <response>
        <phoneNumber>+254733YYYZZZ</phoneNumber>
        <amount>KES 2000.0000</amount>
        <discount>80.0000</discount>
        <status>Failed</status>
        <requestId>ATQid_7gbec14b5c7b876h375848fy8a56c2b</requestId>
        <errorMessage>None</errorMessage>
      </response>
    </responses>
    <errorMessage>None</errorMessage>
  </AirtimeResponse>
 
JSON

{
 "numSent": n,
 "totalAmount": "KES XXX",
 "totalDiscount" : "KES YYY",
 "responses" : [
      {
        "errorMessage":"None",
        "phoneNumber":"+254711XXXYYY",
        "amount":"KES 1000",
        "discount":"40.0000",
        "status":"sent",
        "requestId":"ATQid_4fbec14b3c6b976d398957f9f8a65b3d"
      },
      .
      .
      .
      .
      {
        "errorMessage":"None",
        "phoneNumber":"+254733YYYZZZ",
        "amount":"KES 2000",
        "discount":"80.0000",
        "status":"sent",
        "requestId":"ATQid_7gbec14b5c7b876h375848fy8a56c2b"
      }
  ],
  "errorMessage":"None"
 }