Initiate Airtime Purchase

POST

http://localhost:8080/api/v3/transactions/buy-airtime

POST

/api/v3/transactions/buy-airtime

curl -X POST http://localhost:8080/api/v3/transactions/buy-airtime \
     -H "Authorization: Bearer {{accessToken}}" \
     -H "Idempotency-Key: idem-{{$guid}}" \
     -H "X-Device-Id: {{deviceId}}" \
     -H "X-Request-Id: {{requestId}}" \
     -H "X-Signature: {{signature}}" \
     -H "X-Timestamp: {{timestamp}}" \
     -H "Content-Type: application/json" \
     -d '{
  "walletId": "b1e7f6a0-9d2b-4a5b-9c3d-1a2b3c4d5e6f",
  "amount": 100,
  "networkProvider": "SAFARICOM",
  "phoneNumber": "0712345678"
}'

{
  "code": 200,
  "message": "Airtime purchase initiated.",
  "data": {
    "transactionId": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f81",
    "walletId": "b1e7f6a0-9d2b-4a5b-9c3d-1a2b3c4d5e6f",
    "amount": 100,
    "fee": 0,
    "category": "AIRTIME",
    "destination": "712***678",
    "status": "INITIATED",
    "reference": "UTL9PB2W6D",
    "timestamp": "2026-10-07 13:00:00"
  }
}

Starts an airtime purchase from walletId (a PERSONAL or BUSINESS wallet). networkProvider is SAFARICOM, AIRTEL or TELKOM, and phoneNumber must belong to that network. amount is whole shillings, minimum 10. The response masks the destination number. Next step: Confirm Airtime Purchase with the returned transactionId.

Headers

Request

This endpoint expects an object.

walletIdstringOptional

amountintegerOptional

networkProviderstringOptional

phoneNumberstringOptionalformat: "utc-millisec"

Response

200 OK

codeintegerOptional

messagestringOptional

dataobjectOptional

Errors

400

Bad Request Error