Airtime API South Africa: Supplier Costs & Evaluation

An airtime API lets your software purchase mobile credit for a recipient and retrieve the result. In South Africa, businesses use it for employee allocations, survey incentives, loyalty rewards, reseller applications and customer-service credits across networks such as Vodacom, MTN, Cell C and Telkom.

The first buying decision is whether you need direct recharge or voucher PINs. The second is whether the supplier’s commercial terms and order lifecycle fit your application. A successful HTTP call alone does not answer either question.

This guide uses SIMcloud’s published API contract to make the evaluation concrete. It covers product choice, costs, funding, delivery states and a test plan you can use before committing a campaign or customer base.

Direct recharge, voucher API or bulk portal?

SIMcloud’s airtime endpoint is a direct recharge workflow. Do not assume an airtime endpoint also issues voucher PINs. Likewise, API access may be unnecessary for a monthly file that an operations team can review and submit through Bulk Recharge.

Compare the commercial model before writing code

Get a written price basis for the exact products you will purchase. “Wholesale”, “discounted” and “no monthly fee” do not establish the amount your account will pay for every network and denomination.

Compare product cost, any access or transaction charges, minimum commitments, funding arrangements and support terms. Keep airtime face value separate from your margin. For example, 10,000 rewards at R20 represent R200,000 of airtime face value; that arithmetic does not establish purchase cost, resale profit or a supplier discount.

Funding is an operating requirement. Estimate the money needed for the busiest purchasing period and the time it takes to replenish the account. Ask how funding is matched to your wallet and who resolves an allocation problem. A planned campaign can be fully approved while the purchase wallet is still unable to fund its orders.

SIMcloud’s Balance API returns the account’s stored last known wallet balance with an update timestamp. Treat a balance read as information, not a reservation of money for an entire batch. Other purchases can consume funds between a check and a subsequent order.

What SIMcloud’s airtime API actually accepts

The published contract uses HTTPS and Bearer-token authentication. A purchase is submitted to POST /api/airtime.php with these fields:

The Data API adds a product-selection requirement: fetch the current catalogue and use a valid network and sell-value combination. A successful airtime integration does not mean arbitrary rand values are valid data purchases.

Keep API tokens in your backend, not browser JavaScript or a mobile application distributed to customers. Review the OpenAPI specification with the person who will maintain the integration.

Accepted, pending and delivered mean different things

SIMcloud queues an accepted airtime purchase and returns a request_id. Your application then queries the original order. It should preserve that identifier even if the customer closes the page or the worker restarts.

The initial submission can report status: success while its queue_status is queued. That means the request was accepted; it is not a delivery receipt. Treating it as fulfilment can make your own customer records disagree with the supplier.

Why duplicate protection is not the same as idempotency

The airtime documentation describes a five-minute duplicate rule for the same number and amount, returning HTTP 409. This is useful protection, but it is not a documented promise that repeating a business reference can never create a second charge.

Consider a reward platform that sends a purchase and loses the response. The supplier may have accepted it even though the caller received no usable identifier. Sending it again with a different reference, or waiting for the duplicate window to expire, does not resolve the first order’s outcome.

Your application needs a durable record of the intended purchase before submission, a record of any returned identifier, and an explicit unresolved state when the response is ambiguous. Agree a recovery procedure with the supplier. A customer refreshing a page should not create a fresh reward event.

Also consider legitimate repeated purchases: two R20 rewards for the same number within five minutes can encounter the duplicate rule. Check that constraint against your campaign design rather than discovering it after launch.

Keep your own purchase ledger

A useful internal record connects the business event, recipient, product, intended amount, supplier request ID, final status and relevant timestamps. Restrict access to recipient information and credentials. Finance and support should be able to trace the same purchase using its identifiers.

SIMcloud’s Transaction History API provides account-owned transaction identifiers, service, status, reason, reference and timestamps. It does not return recipients, prices or wallet values. It can help reconcile operational outcomes, but it does not replace your purchase ledger or prove a financial settlement on its own.

There is also a naming distinction to handle: the recharge query uses delivered for successful delivery; the history endpoint normalises successful transactions to success. Map those explicitly rather than assuming every endpoint uses the same vocabulary.

When reading history, follow next_cursor with the same filters until all pages are retrieved. The documented maximum date range is 90 days. A single first-page response is not necessarily a complete campaign record.

A supplier evaluation that tests more than a happy path

Agree the test scope and budget before making real purchases. Confirm whether a sandbox or test-credit arrangement exists; do not assume production orders are free. Use authorised test numbers and keep intentional failure tests separate from customer campaigns.

Record completion times by network and the age of unresolved orders during the agreed evaluation. A few successful requests do not establish an availability guarantee or sustained throughput. Obtain explicit commitments for requirements that are essential to your business.

When SIMcloud is worth evaluating

SIMcloud is relevant when you need South African direct airtime or data fulfilment, wallet-based purchases and documented order-status queries. For cross-border products, voucher PIN requirements, credit terms or a specific service-level agreement, establish availability separately before designing around them.

Bring your network mix, product requirements, monthly orders and purchasing value, busiest expected submission period and target launch date. Explain whether your software already has a purchase ledger and background processing. That makes the conversation about the actual integration rather than a generic API demonstration.

Discuss your airtime API requirements with Dave. For implementation detail, continue to the airtime distribution platform guide.

Airtime API questions

API details checked against SIMcloud’s published airtime, data, balance, transaction-history and OpenAPI documentation on 29 September 2026. Recheck the current contract before implementation.