Skip to main content

​
Overview

The Airtime service provides endpoints for sending airtime to phone numbers and handling validation and status callbacks through Africa’s Talking Airtime API.

​
GET /airtime/

Check Airtime service status.

​
Response

​
service
string
Service name (“airtime”)
​
status
string
Service status (“ready”)

​
Example Request

curl -X GET http://localhost:5000/airtime/

​
Example Response

{
  "service": "airtime",
  "status": "ready"
}

​
GET /airtime/invoke-send-airtime

Send airtime to a phone number.

​
Query Parameters

​
phone
string
required
Phone number to send airtime to (without the + prefix, e.g., 254711XXXYYY)
​
amount
string
default:"10"
Amount of airtime to send (must be a positive number)
​
currency
string
default:"KES"
Currency code (e.g., KES, USD, UGX)
​
idempotencyKey
string
default:"ABCDEF"
Idempotency key to prevent duplicate transactions

​
Response

​
message
string
Success message indicating airtime was sent
​
response
object
Response object from Africa’s Talking API

​
Example Request

curl -X GET "http://localhost:5000/airtime/invoke-send-airtime?phone=254711XXXYYY&amount=100&currency=KES"

​
Example Response

{
  "message": "Airtime sent to +254711XXXYYY",
  "response": {
    "errorMessage": "None",
    "numSent": 1,
    "totalAmount": "KES 100.0000",
    "totalDiscount": "KES 0.6000",
    "responses": [
      {
        "phoneNumber": "+254711XXXYYY",
        "errorMessage": "None",
        "amount": "KES 100.0000",
        "status": "Sent",
        "requestId": "ATQid_SampleTxnId123",
        "discount": "KES 0.6000"
      }
    ]
  }
}

​
Error Codes

  • 400 - Missing ‘phone’ query parameter, invalid amount (must be positive number)
  • 500 - Internal server error or Africa’s Talking API error

​
POST /airtime/validation

Validation callback webhook for airtime transactions.

​
Request Body (JSON)

​
transactionId
string
required
Unique transaction ID
​
phoneNumber
string
required
Phone number receiving airtime
​
sourceIpAddress
string
required
Source IP address of the transaction
​
currencyCode
string
required
Currency code (e.g., KES, USD)
​
amount
number
required
Amount of airtime being sent

​
Response

​
status
string
Validation status: “Validated” or “Failed”

​
Example Request

curl -X POST http://localhost:5000/airtime/validation \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "SomeTransactionID",
    "phoneNumber": "+254711XXXYYY",
    "sourceIpAddress": "127.12.32.24",
    "currencyCode": "KES",
    "amount": 500.00
  }'

​
Example Response

{
  "status": "Validated"
}

​
Error Codes

  • 400 - Missing required fields

​
POST /airtime/status

Status callback webhook for airtime delivery updates.

​
Request Body (JSON)

​
phoneNumber
string
required
Phone number that received airtime
​
description
string
required
Description of the delivery status
​
status
string
required
Delivery status (e.g., “Success”, “Failed”)
​
requestId
string
required
Request ID from the original airtime send request
​
discount
string
required
Discount amount applied (e.g., “KES 0.6000”)
​
value
string
required
Total value sent (e.g., “KES 100.0000”)

​
Response

Returns “OK” with status 200.

​
Example Request

curl -X POST http://localhost:5000/airtime/status \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+254711XXXYYY",
    "description": "Airtime Delivered Successfully",
    "status": "Success",
    "requestId": "ATQid_SampleTxnId123",
    "discount": "KES 0.6000",
    "value": "KES 100.0000"
  }'

​
Example Response

OK

​
Status Values

Common status values:
  • Success - Airtime delivered successfully
  • Failed - Airtime delivery failed
  • Sent - Airtime has been sent to the network
  • Queued - Transaction is queued for processing
  • InvalidRequest - Request was invalid
  • NotSupported - Operation not supported for this number
  • InsufficientBalance - Insufficient balance in your account
  • UserInInvalidState - User account is in invalid state
  • UserNotFound - Phone number not found on network

​
Error Codes

  • 400 - Missing required fields in request body

Build docs developers (and LLMs) love

Get started for freeTalk to us