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

The code uses VB gateway class: AfricasTalkingGateway.vb [ Download]

The code encodes and decodes data using Javascript serializer so you will need to add System.Web.Extensions to your referenced libraries


Imports System.IO
Imports System.Collections
Imports System.Collections.Generic

Public Class Application
	Public Shared Sub Main()
		
			' Specify your login credentials
			
			Dim username As String = "myAfricasTalkingUsername"
			Dim apikey As String   = "myAPIKey"
			
			' Specify an list to hold the airtime recipient numbers and the amount to be sent
			
			Dim airtimeRecipientsList As New List(Of Hashtable)()
			
			' Declare hashtable to hold the first recipient and amount sent to them
			' Please ensure you include the country code for phone numbers (+254 for Kenya in this case)
			' Specify the country currency and the amount as shown below (KES for Kenya in this case)
			
			Dim recipient1 As New Hashtable()
			recipient1("phoneNumber") = "+254711XXXYYY"
			recipient1("amount")      = "KES XX"
			
			' Add the recipient to airtimeRecipientsList
			airtimeRecipientsList.add(recipient1)
			
			
			' Declare hashtable to hold the second recipient
			
			Dim recipient2 As New Hashtable()
			recipient2("phoneNumber") = "+254733YYYZZZ"
			recipient2("amount")      = "KES YY"
			
			' Add the recipient to airtimeRecipientsList
			airtimeRecipientsList.add(recipient2)
			
			' Create a new instance of our awesome gateway class
			Dim gateway As New AfricasTalkingGateway(username, apikey)
			
			
			Try
			 ' Hit send and we will handle the rest
				Dim response as object()= gateway.sendAirtime(airtimeRecipientsList)
				
				Dim result as object
				for each result in response
					System.Console.WriteLine("Status: " + result("status"))
					System.Console.WriteLine("RequestID: " + result("requestId"))
					System.Console.WriteLine("phoneNumber: " + result("phoneNumber"))
					System.Console.WriteLine("Discount: " + result("discount"))
					System.Console.WriteLine("amount: " + result("requestId"))
					
					' Incase the status result is Failed
					System.Console.WriteLine("ErrorMessage: " + result("errorMessage"))
				next
		catch ex As AfricasTalkingGatewayException
			System.Console.WriteLine(ex.Message())
		End Try 
	End Sub
End Class

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