Airtime API Documentation

Base URL

https://simcloud.co.za/api/airtime.php

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

How It Works

Submit an airtime purchase request with POST.
SIMcloud queues the request and returns a request_id.
Poll the same endpoint with GET until the status changes from queued or pending to a final status.
Only orders that belong to the authenticated account can be queried.
The same MSISDN and amount cannot be ordered again within 5 minutes. Duplicate requests inside that window return 409.

Supported Airtime Networks

mtn or p-mtn
cellc, cell-c, cell c or p-cellc
vodacom or p-vodacom
telkom, heita or p-heita

Endpoints

1. Place Airtime Order

POST Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
msisdn	string	Yes	South African mobile number to recharge.
network	string	Yes	Network name or internal code such as `mtn` or `p-mtn`.
amount	number	Yes	Recharge amount in rand. Must be between 2 and 999.
reference	string	Yes	Your own reference for the request.

Example Request

{
    "msisdn": "0821234567",
    "network": "p-mtn",
    "amount": 10.00,
    "reference": "Airtime for John"
}

Success Response

{
    "status": "success",
    "message": "Airtime order queued successfully",
    "request_id": 1527245,
    "service": "airtime",
    "msisdn": "+27821234567",
    "network": "p-mtn",
    "amount": 10,
    "reference": "Airtime for John",
    "queue_status": "queued",
    "timestamp": "2026-04-16 16:00:00"
}

Insufficient Balance Response

{
    "status": "error",
    "message": "Insufficient balance. Please top up your account.",
    "required_balance": 10,
    "available_balance": 4
}

Duplicate Order Response

{
    "status": "error",
    "message": "An order for the same MSISDN and amount has been placed in the last 5 minutes."
}

2. Query Airtime Order

GET

Query Parameters

Parameter	Type	Required	Description
request_id	integer	No	Queue request ID returned by the POST request.
orderno	string	No	Platform order number once it has been allocated.

At least one of the two query parameters is required.

Example Request

GET https://simcloud.co.za/api/airtime.php?request_id=1527245

Pending Response

{
    "status": "pending",
    "service": "airtime",
    "request_id": 1527245,
    "msisdn": "+27821234567",
    "network": "p-mtn",
    "amount": 10,
    "reference": "Airtime for John",
    "platform_order_number": "123456789",
    "queue_status": "Order Placed",
    "final_order_id": 1395228,
    "final_order_status": null,
    "error": null,
    "created_at": "2026-04-16 16:00:00",
    "updated_at": "2026-04-16 16:00:40"
}

Delivered Response

{
    "status": "delivered",
    "service": "airtime",
    "request_id": 1527245,
    "msisdn": "+27821234567",
    "network": "p-mtn",
    "amount": 10,
    "reference": "Airtime for John",
    "platform_order_number": "123456789",
    "queue_status": "Order Placed",
    "final_order_id": 1395228,
    "final_order_status": "delivered",
    "error": "Success",
    "created_at": "2026-04-16 16:00:00",
    "updated_at": "2026-04-16 16:01:30"
}

Statuses

queued: Request is stored locally and waiting to be placed.
pending: Platform order number exists, but final delivery status is not back yet.
delivered: Airtime order completed successfully.
failed: Airtime order failed.

Error Codes

Code	Description
400	Bad Request (missing or invalid parameters)
401	Unauthorized (invalid or missing token)
404	Order not found for this account
409	Duplicate order detected within the 5-minute rule window