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 PHP code snippet below shows how to send airtime using our API.

The code uses our PHP gateway class: AfricasTalkingGateway.php [ Download]

Also, please ensure that you have the php_curl module enabled. To enable it uncomment the line: ;extension=php_curl.dll in php.ini and restart apache

<?php

require_once "AfricasTalkingGateway.php";

//Specify your credentials
$username = "myAfricasTalkingUsername";
$apiKey   = "myAfricasTalkingAPIKey";

//Specify the phone number/s and amount in the format shown
//Example shown assumes we want to send KES 100 to two numbers
// 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)

$recipients = array(
	array("phoneNumber"=>"+254711XXXYYY", "amount"=>"KES 100"),
	array("phoneNumber"=>"+254733YYYZZZ", "amount"=>"KES 100")
);

//Convert the recipient array into a string. The json string produced will have the format:
// [{"amount":"KES 100", "phoneNumber":"+254711XXXYYY"},{"amount":"KES 100", "phoneNumber":"+254733YYYZZZ"}]
//A json string with the shown format may be created directly and skip the above steps
$recipientStringFormat = json_encode($recipients);

//Create an instance of our awesome gateway class and pass your credentials
$gateway = new AfricasTalkingGateway($username, $apiKey);

/*************************************************************************************
 NOTE: If connecting to the sandbox:

 1. Use "sandbox" as the username
 2. Use the apiKey generated from your sandbox application
	https://account.africastalking.com/apps/sandbox/settings/key
 3. Add the "sandbox" flag to the constructor

 $gateway  = new AfricasTalkingGateway($username, $apiKey, "sandbox");
**************************************************************************************/

// Thats it, hit send and we'll take care of the rest. Any errors will
// be captured in the Exception class as shown below

try {
$results = $gateway->sendAirtime($recipientStringFormat);

foreach($results as $result) {
	echo $result->status;
	echo $result->amount;
	echo $result->phoneNumber;
	echo $result->discount;
	echo $result->requestId;
	
	//Error message is important when the status is not Success
	echo $result->errorMessage;
}
}
catch(AfricasTalkingGatewayException $e){
echo $e->getMessage();
}

//Done
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"
 }