Airtime

This section provides details about the Airtime API, including endpoints for direct airtime purchase and airtime voucher purchase.

Direct Airtime Purchase

Allows users to directly purchase airtime for a specified mobile number.

Purchase airtime directly for a specified mobile number.

POST https://domain.xash.co.zw/api/airtime/direct

Headers

Name	Type	Description
Authorization*	String	This endpoint requires a Firebase Bearer token for authorization. The token should be included in the Authorization header in the format Bearer {token}.

Request Body

Name	Type	Description
mobile_number*	String	The target mobile number for airtime top-up.
amount*	String	The amount of airtime to be purchased.
currency*	String	Either ZWL or USD

200: OK Successfully purchased direct airtime.

{
  "status": "success",
  "transaction_id": "ABC123",
  "target_balance": 150
}

400: Bad Request Invalid request, likely due to balance or invalid `body` parameters

401: Unauthorized

Get List of Airtime Vouchers

Get a list of available airtime vouchers. You can filter the vouchers by network, currency, and amount.

Get Vouchers

GET https://domain.xash.co.zw/api/v1/airtime/vouchers

This endpoint provides a list of available airtime vouchers based on specified filters, including network, currency, and amount. The response includes details such as network, currency, value, and a distinct of unique voucher types.

Query Parameters

Name	Type	Description
network	String	Filter vouchers by network (e.g., "NetOne", "Econet", "Telecel").
currency	String	Filter vouchers by currency (e.g., "USD", "ZWL").
amount	Float	Filter vouchers by a specific amount.
min_amount	Float	Minimum value for filtering vouchers by amount (used optionally with max_amount).
max_amount	Float	Maximum value for filtering vouchers by amount (used optionally with min_amount).

Headers

Name	Type	Description
Authorization*	String	This endpoint requires a Firebase Bearer token for authorization. The token should be included in the Authorization header in the format Bearer {token}.

200: OK Successful

{
  "vouchers": [
    {
      "network": "Econet",
      "currency": "USD",
      "value": 20
    },
    {
      "network": "Econet",
      "currency": "USD",
      "value": 50
    }
    // ... other voucher types
  ],
  "distinct": 2
}

401: Unauthorized

// JavaScript example using fetch
fetch('/airtime/vouchers?network=Econet&currency=USD&amount=20')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Airtime Voucher Purchase

This API allows users to purchase airtime vouchers.

Purchase airtime vouchers.

POST https://domain.xash.co.zw/api/v1/airtime/vouchers/buy

This endpoint enables users to buy airtime vouchers based on the provided network, currency, quantity, and value. The operation performs a series of checks, including validating the input parameters, checking the user's balance, and processing the airtime purchase. Upon successful purchase, the API returns details of the purchased vouchers.

Headers

Name	Type	Description
Authorization*	String	This endpoint requires a Firebase Bearer token for authorization. The token should be included in the Authorization header in the format Bearer {token}.

Request Body

Name	Type	Description
network*	String	The network for which the vouchers are being purchased.
value*	Float	The value of each voucher (From list of vouchers above)
quantity*	Integer	The quantity of vouchers to be purchased (must be greater than or equal to 1).
currency*	String	The currency in which the vouchers are priced.

200: OK

  {
    "message": "Voucher purchased successfully",
    "vouchers": [
      {
        "value": 10,
        "currency": "USD",
        "network": "Econet",
        "pin": "1234567890123456" 
      },
      // Additional voucher objects if quantity is more than 1
    ]
  }

401: Unauthorized

400: Bad Request *422 Unprocessable Entity Error