Universal airtime voucher API for South African businesses

Universal voucher PINs and direct recharge

The AllNet Vendor API orders voucher PINs. You choose the value and quantity without supplying each recipient's network in the order request. The recipient later uses the PIN to redeem prepaid airtime on a supported South African network.

A direct recharge integration sends airtime to a specified number as part of the purchase workflow. Choose the voucher workflow when your business needs to distribute a redeemable code. The public AllNet API does not expose voucher redemption as a vendor operation.

This model can fit campaign rewards and incentives where your application approves a reward and supplies a PIN. Your application controls the campaign rules and recipient distribution.

Authentication and account balance

The production base URL is https://allnetairtime.co.za. Protected vendor operations use the X-API-Key header. The API contract also documents vendor registration and the fields needed to create an account.

Keep the API key in your server-side integration. Do not publish it in page source or pass it to a browser as a client-side credential. Use the documented balance operation to retrieve the current ZAR vendor balance before planning an order.

The following balance request is an example. Replace YOUR_API_KEY with your vendor key in your own secure environment.

curl https://allnetairtime.co.za/api/balance.php \
  -H "X-API-Key: YOUR_API_KEY"

Documented vendor operations

POST /api/register.php

Register a vendor account using the required fields in the contract.

GET /api/balance.php

Retrieve the current vendor wallet balance in ZAR.

POST /api/order.php

Order a quantity of universal airtime vouchers at a chosen value.

GET or POST /api/fetch_order.php

Retrieve an order and its associated vouchers by order reference or ID.

POST /api/voucher_status.php

Query redemption status for one voucher owned by your vendor account.

POST /api/unredeemed_vouchers.php

Retrieve a paginated list of unredeemed vouchers from your account's orders.

The API documentation and published OpenAPI contract define the request fields, authentication, responses and errors. Use that contract when implementing these operations.

Order values, quantities and references

A voucher order requires an integer quantity of at least one and an integer value from R2 to R999. The optional description can describe your order. A request for two R20 vouchers has R40 in voucher face value.

{
  "quantity": 2,
  "value": 20,
  "description": "Campaign rewards"
}

Retain the order ID and reference returned in a successful response, then retrieve the associated vouchers through the documented order lookup. Store PINs securely and maintain the link between an order and the business event that required it.

If an order request times out, do not assume that no order was created. Check the result using an available order reference or ID, or contact Freepaid if the outcome cannot be established. Avoid blindly repeating a purchase request. Do not assume that the order description or generated reference provides a documented idempotency mechanism.

Keep ordering, distribution and redemption separate

An order creates the vouchers your account can retrieve. Giving a PIN to a recipient and that recipient redeeming airtime are separate steps. The status and unredeemed-voucher operations can support your reporting, but an order response is not a confirmation that every recipient has received airtime.

The dashboard's SMS service is a distribution option. Do not assume the public Vendor API includes an SMS-sending endpoint. Supply recipients with the USSD or online redemption instructions alongside their PIN.