Airtime

Send airtime

Top up a mobile number with airtime.

Checks that your account has sufficient balance, then places an order. A webhook delivers the final status; you can also retrieve the airtime order from the transaction status endpoint.

POST /v1/airtime

Services

Pass the service name in the service field. If omitted, the service can be auto-detected from the account number prefix.

Service	Description
`safaricom`	Safaricom
`airtel`	Airtel
`telkom`	Telkom Kenya
`jtl`	JTL
`equitel`	Equitel

Request

cURL POST /v1/airtime

curl -X POST https://api.buyairtime.co.ke/v1/airtime \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  -d '{
    "service":       "safaricom",
    "account":       "0733000000",
    "amount":        10,
    "currency":      "KES",
    "reference":     "ref1234",
    "idempotencyKey": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name":          "John",
    "phone":         "254722000000",
    "shortcode":     "100100"
  }'

Authentication: Include the bearer token returned by the authorization flow in every request. Use a unique Idempotency-Key header for each intended transaction. The idempotencyKey body field is supported as an alternative.

service string required

Airtime service identifier — see Services above. This field is required.

account string required

Recipient phone number.

amount number required

Amount to top up.

currency string required

Currency code.

reference string required

Your internal reference.

idempotencyKey string

Unique UUID per request — prevents duplicate orders on retry.

Live-state replay

Airtime is a fast-delivery flow: the initial POST can return with status: 0 ("Pending") while the top-up completes asynchronously. Retrying with the same idempotencyKey returns the same transaction ID with the latest transaction status. Reusing the key with a different payload returns 409 idempotency_payload_mismatch.

name string

Customer first name.

phone string

Customer phone number.

shortcode string

Your own M-Pesa shortcode (paybill or till) — not a telco code. Selects which of your wallets funds and is billed for the order when your business has more than one. Omit it and your default wallet is used. The telco is chosen by service, never by this field.

Response

JSON 200 OK

{
  "id":        "ABCDEFG250101",
  "reference": "ref1234",
  "status":    0,
  "message":   "Pending"
}

idstring

Transaction ID (absent on failure).

referencestring

Your internal reference.

statusnumber

See the Status Codes documentation.

messagestring

Human-readable status.

Request flow

Authenticate and obtain a bearer token.
Send the airtime request with the recipient, amount, service and idempotency key.
Store the returned transaction ID and reference.
Use webhooks for the final transaction state or retrieve the transaction status when needed.