How to Build an Airtime Distribution Platform with the SIMcloud API

An airtime distribution platform gives a business one controlled way to approve, send and reconcile airtime for employees, field teams, customers or managed devices. The SIMcloud Airtime API supplies queue-based recharge fulfilment; your platform supplies recipients, policy, approval, duplicate control and reporting.

Define the platform scope

Decide which use cases are allowed:

• Scheduled employee allowances.
• Approved once-off operational recharges.
• Customer promotions or service recovery.
• Managed-device connectivity.
• Reseller or downstream customer orders.

For each use case define approvers, allowed amounts, frequency, network validation, budget owner and failed-order treatment.

Use a queue-based architecture

A reliable design has:

1. An authenticated order-entry API or scheduled allowance job.
2. A local orders table with a unique immutable reference.
3. An approval and budget check.
4. A network lookup or trusted recent network result.
5. A SIMcloud submission worker.
6. A polling worker for queued and pending orders.
7. A reconciliation report for delivered and failed results.

Do not call SIMcloud directly from browser code. Do not keep a web request open while waiting for a final recharge result.

Store the order lifecycle

Validate before submission

The Airtime API requires msisdn, network, amount and reference. The current amount range is R2 to R999. Validate against your programme limits, which may be narrower.

Confirm the current network instead of relying permanently on the number prefix. Use the Network Lookup API when the stored network is absent or stale.

Submit one airtime order

POST https://simcloud.co.za/api/airtime.php
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "msisdn": "0821234567",
  "network": "mtn",
  "amount": 10.00,
  "reference": "ALLOWANCE-2026-07-000184"
}

HTTP 201 returns the SIMcloud request_id, normalised number, network, amount, reference and queue state. Store the response before scheduling status work.

Design around duplicate protection

SIMcloud returns HTTP 409 when the same MSISDN and amount has been ordered inside the documented five-minute window. Your platform should also prevent duplicate local references before calling the API.

Use three layers:

• A unique client reference.
• A local idempotency constraint for the programme event.
• SIMcloud’s same-number-and-amount five-minute duplicate guard.

Poll the original request

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

Queued and pending require later polling. Delivered and failed are final. Update the existing local row; never create a new order to make a pending row disappear.

Manage wallet readiness

Use the Balance API for operational monitoring and a pre-check, but do not treat the returned last known balance as a reservation. Maintain alert thresholds and pause new programme releases when the wallet cannot cover the approved run.

Reconcile every allowance or distribution run

Report approved, submitted, delivered and failed counts and values. Match records by immutable local reference and SIMcloud request ID. Investigate orders without approval, approvals without orders, repeated references and pending orders beyond the operational threshold.

Frequently asked questions