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

The code uses our Python gateway class: AfricasTalkingGateway.py [ Download]

# Import the helper gateway class
from AfricasTalkingGateway import AfricasTalkingGateway, AfricasTalkingGatewayException

# Specify your login credentials
username   = "MyUsername";
apikey     = "MyAPIKey";

# Specify an array of dicts to hold the recipients and the amount to send
recipients = [{"phoneNumber" : "+254711XXXYYY", 
               "amount"      : "KES XX"}]

# Create a new instance of our awesome gateway class
gateway = 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 = AfricasTalkingGateway(username, apiKey, "sandbox");
#**************************************************************************************

try:
    # Thats it, hit send and we'll take care of the rest. 
    responses = gateway.sendAirtime(recipients)
    for response in responses:
        print "phoneNumber=%s; amount=%s; status=%s; discount=%s; requestId=%s" % (
                                                                       response['phoneNumber'],
                                                                       response['amount'],
                                                                       response['status'],
                                                                       response['discount']
                                                                       response['requestId']
                                                                      )

except AfricasTalkingGatewayException, e:
    print 'Encountered an error while sending airtime: %s' % str(e)
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"
 }