Airtime

As a PesaWay merchant, you can send airtime to your customers / employees through various networks. The Airtime API is applicable in various use cases such as Selling Airtime, Airtime allowance distribution, etc.

Alt test Endpoint: https://api.sandbox.pesaway.com/api/v1/airtime/send-airtime/

Supported Networks

Country	Network
Kenya	Safaricom, Airtel, Telkom
Uganda	MTN, Airtel
Tanzania	Tigo / Yas, Vocacom, Airtel, Halo

Request Parameters

Field	Type	Description	Examples
Amount	Number	The amount of money being sent to the customer.	30.00
ExternalReference	Alpha-Numeric	A unique identifier of the transaction generated by the Merchant system.	"1234"
PhoneNumber	Numeric	This is the customer mobile where the funds are to be received. Mobile number must include country code eg. 254712345678	2547*******8
Reason	Alpha-Numeric	The reason for airtime transacton.	"Airtime of project ABC"
ResultsUrl	URL	This is the URL to be specified in your request that will be used to send notification upon processing of the airtime transacton request	"https://yourdomain.com/result_url"

Sample Request

curl --location 'https://api.sandbox.pesaway.com/api/v1/airtime/send-airtime/' \
--header 'X-Region: ke' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "ExternalReference": "202511051829",
    "Amount": 1000,
    "PhoneNumber": "2547xxxxxxx",
    "MerchantCode": "44444",
    "Currency": "KES",
    "Description": "Airtime Transfer",
    "ResultsUrl": "https://callback-url"
}''

TIP

Alway include the X-Region header on all requests. The right X-Region can be found on the Supported Regions / Countries menu

Response Parameters

Field	Type	Description	Example
code	String	This is a status code for either success or failure of the transaction	"200.001"
TransactionID	String	An identifier for the transaction request returned by PesaWay upon successful request submission. This is generated by PesaWay API.	"PHY20ADFASFASFS"
OriginatorReference	String	An identifier for the transaction request from the merchant side. It is the input given as TransactionReference when sending B2C request.	"123344"

Response Sample

{
  "code": "200.001",
  "OriginatorReference": "202511051830",
  "TransactionID": "PHYAEAE707E0A",
  "ResponseDescription": "Success. Request accepted for processing"
}

Callback Response

This is the callback data that will be sent to your ResultsUrl. To Simulate a failed response, use the following phone number: 980321123123

Field	Type	Description	Example
ResultCode	Numeric	The numeric status of the results, sent to the callback url 0 means success, while any other code indicates that an error occurred.	field
ResultDesc	String	This is a message from the API that gives the status of the request processing and usually maps to a specific result code value.	"The service request is processed successfully"
TransactionID	String	This is a unique PesaWay transaction ID for every airtime transacton request. Same value is sent to the customer over SMS upon successful processing.	PR52
PhoneNumber	String	This is the customer mobile where the funds are to be received. Mobile number must include country code eg. 254712345678	QTD6ADFSAs
TransactionAmount	Number	This is the amount that was transacted. It is usually returned under the ResultParameter array.	"10.00"
OriginatorReference	Decimal	A unique identifier of the transaction generated by the Merchant system.	"202511051835"
TransactionCompletedDateTime	String	This is the date and time that the transaction completed PesaWay.	"20220305103101"
AccountAvailableFunds	Decimal	This is the available balance after the transaction.	564.00

Sample Success Result Response

{
  "ResultCode": 0,
  "ResultDesc": "The airtime request is processed successfully.",
  "OriginatorReference": "202511051835",
  "PhoneNumber": "2547xxxxxxx",
  "TransactionID": "PHY21A7531067",
  "TransactionAmount": "1000.00",
  "AccountAvailableFunds": "88000.00",
  "TransactionCompletedDateTime": "2025-11-06 03:49:34.510325+00:00"
}

Sample Failed Result Response

{
  "ResultCode": 2001,
  "ResultDesc": "Transaction failed",
  "OriginatorReference": "202511051836",
  "TransactionID": "PHYF27E843259",
  "TransactionAmount": "1000.00",
  "TransactionReceipt": null
}