South African airtime, data, SMS and electricity APIs: guides and sample code

Integration guides, field-by-field references and runnable sample code in 13 languages for two South African prepaid platforms from FREEPAID (PTY) LTD:

• Freepaid Airtime API: a SOAP API for wholesale airtime and data (Vodacom, MTN, Cell C, Telkom).
• SIMcloud REST API: a JSON API for airtime, data, SMS, VAS vouchers and prepaid electricity.
• SIMcloud MCP server: lets AI assistants (Claude, ChatGPT, Codex, Cursor, VS Code) use a SIMcloud account, with worked use cases.

Everything runs offline first. Each API folder ships a local mock server, so you can build and test with no account and no money.

Choose a folder

Not sure which API? If you want JSON, SMS, vouchers or electricity, use SIMcloud. If you already have a Freepaid account and a SOAP integration, or want the Freepaid wholesale PINNED vouchers, use Freepaid. If you want an AI assistant to do the work, use the MCP server.

Languages

Both APIs have the same commands in every language. "Tested" means it ran a full scenario against the local mock.

"Written" means not executed here. The C#, PowerShell, PL/SQL and ABAP samples send the same requests as the tested ones, but no .NET SDK, PowerShell, Oracle database or SAP system was available to run them. Each file says so in its header. Run them against the mock first and report anything that breaks.

COBOL, RPG, Kotlin, Scala and other stacks: see the language notes in each API folder for how to approach them.

Quick start

git clone https://github.com/ErikThiart/airtime-api.git
cd airtime-api

# Freepaid (SOAP) with Python, no packages needed
python3 freepaid-api/mock-server/mock_freepaid.py &
cd freepaid-api/samples/python && python3 freepaid.py balance

# SIMcloud (REST)
cd ../../../simcloud-api
python3 mock-server/mock_simcloud.py &
cd samples/python && python3 simcloud.py airtime 0821234567 vodacom 10 "Test"

To use the real services, set the environment variables listed in each folder's README. Every sample defaults to its mock, so nothing spends money by accident.

Things worth knowing

• The Freepaid WSDL is RPC/encoded, which Java's JAX-WS, .NET's WCF and Python's zeep cannot consume. Every Freepaid sample builds the envelope by hand. Details.
• Orders are not idempotent. Freepaid does not enforce unique references, and SIMcloud queues orders. Both folders explain how to avoid double spends. Start with Freepaid or SIMcloud.
• Treat PINs, voucher codes and electricity tokens as cash. Do not log them.
• The Freepaid sandbox hostnames in the original guide did not resolve on 8 November 2026. Ask Freepaid for current sandbox access and use the mock meanwhile. Details.

Run the tests

./freepaid-api/tests/run-samples.sh     # every installed language, against the Freepaid mock
./simcloud-api/tests/run-samples.sh     # the same for SIMcloud

Languages whose toolchain is not installed are skipped and listed.

Repository layout

airtime-api/
  README.md              this page
  freepaid-api/          SOAP API: docs, samples, mock server, WSDL, tests
  simcloud-api/          REST API: docs, samples, mock server, OpenAPI, tests
  simcloud-mcp/          MCP server: docs, use cases, client config, samples

Support and sources

The guides and samples here are maintained by Erik Thiart. The mock servers follow the published WSDL, OpenAPI file and documentation, and are not the real services: always confirm behaviour with the provider and test live with small amounts. The original Freepaid guide is kept as freepaid-api/docs/original-vendor-guide.md. Freepaid and SIMcloud are products of FREEPAID (PTY) LTD.