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

The code uses our Ruby and Rails gateway class: AfricasTalkingGateway.rb [ Download]

# Include the helper gateway class
require './AfricasTalkingGateway'

# Specify your login credentials
username = "MyAfricasTalkingUsername";
apikey   = "MyAfricasTalkingAPIKey";

#Create an array to hold all the recipients
recipients = Array.new

#Add the first recipient
recipients[0] = {"phoneNumber" => "+254711XXXYYY", "amount" => "KES XX"}

#Another reciepient
recipients[1] = {"phoneNumber" => "+254733YYYZZZ", "amount" => "KES YY"}

# Create a new instance of our awesome gateway class
gateway = AfricasTalkingGateway.new(username, apikey)

# Any gateway errors will be captured by our custom Exception class below,
# so wrap the call in a try-catch block
begin
  # Thats it, hit send and we'll take care of the rest.
  results = gateway.sendAirtime(recipients)
  results.each {|x|
    # Note that only the Status "Success" means the airtime was sent
    puts 'number=' + x.phoneNumber + '; status=' + x.status + '; requestId=' + x.requestId + '; amount=' + x.amount + "; discount=" + x.discount
	
	#incase the status is not equal to success, it is important to list the error message
	puts 'ErrorMessage=' + x.errorMessage
  }
rescue AfricasTalkingGatewayException => ex
  puts 'Encountered an error: ' + ex.message
end

# 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"
 }