Airtime

Airtime top-ups for the SIMs inside onboard devices. Buy airtime, review purchase history for a device/account, and poll the status of an airtime transaction.

3 endpoint(s)

GET Airtime Purchase History {{url}}/airtime/history/68b86410-e6e8-4b5f-9a3d-8265a7773c0e ▸

Retrieve a school's paginated history of airtime purchases (mobile airtime top-ups, typically for SIM-enabled tracking devices).

Path Parameters

id (string UUID, required): The Administrative Staff (school) UUID whose purchase history to fetch.

Query Parameters

per_page (integer, optional, default 10, max 20)
status (string, optional): SUCCESS, ACKNOWLEDGED, PENDING, or FAILED.
actionbyid (string UUID, optional): Filter to purchases made by a specific staff member.
search (string, optional): Matches provider reference, external reference, or correlation ID.

Response

Paginated list of airtime purchases (data) with meta.

Auth

Bearer token

Request Body

{
    "action_by_id": "68b86410-e6e8-4b5f-9a3d-8265a7773c0e",  // UUID of the user performing the action
    "search": "",  // Free-text search (name / phone / email)
    "per_page": 10,  // Page size — how many results per page
    "page": 1  // Page number (starts at 1)
}

Sample Response (200 OK)

{
    "data": [],
    "links": {
        "first": "http://localhost:8001/api/airtime/history/68b86410-e6e8-4b5f-9a3d-8265a7773c0e?page=1",
        "last": "http://localhost:8001/api/airtime/history/68b86410-e6e8-4b5f-9a3d-8265a7773c0e?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": null,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://localhost:8001/api/airtime/history/68b86410-e6e8-4b5f-9a3d-8265a7773c0e?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "page": null,
                "active": false
            }
        ],
        "path": "http://localhost:8001/api/airtime/history/68b86410-e6e8-4b5f-9a3d-8265a7773c0e",
        "per_page": 10,
        "to": null,
        "total": 0
    },
    "status": 200,
    "message": "Airtime History retrieved Successfully"
}

POST Buy Airtime {{url}}/airtime/buy ▸

Purchase mobile airtime for a phone number via the Lipad payment gateway (used to top up SIM cards in tracking devices, or a driver's phone).

Request Body

phone_number (string, required): Number to top up.
amount (integer, required, min 1): Amount to purchase, in the smallest currency unit.

Response

An AirtimeTransaction record. A successful submission means Lipad acknowledged the request (response_code 720) — it doesn't necessarily mean the airtime has landed yet. Poll AirtimeStatus to confirm completion.

Notes

The transaction is attributed to the requesting Administrative Staff (or their supervisor, if the requester is Staff).

Auth

Bearer token

Request Body

{
"phone_number": "+254715544432",  // Phone number, international format (e.g. +2547XXXXXXXX)
"amount": 10  // Amount in KES
}

Sample Response (422 Unprocessable Entity)

{
    "status": 422,
    "data": {
        "response": {
            "msg": "Lipad Airtime Request Failed",
            "success": 0,
            "response": {
                "reference": "50cc7ff0-3309-4cca-9604-b74e794fd1df",
                "status_code": "Rejected",
                "status_description": "The request failed",
                "error_code": "UNAUTHORIZED",
                "message": "Invalid Auth Parameters"
            }
        }
    },
    "message": "Airtime Purchase failed for: +254715544432"
}

GET Check Airtime Transaction Status {{url}}/airtime/check-status/50cc7ff0-3309-4cca-9604-b74e794fd1df ▸

Poll Lipad for the current status of a previously submitted airtime purchase.

Path Parameters

id (string UUID, required): The airtime transaction UUID returned by Buy Airtime (not a phone number or device ID).

Notes

Returns 404 if the transaction doesn't exist.

Auth

Bearer token

Sample Response (500 Internal Server Error)