# SIMcloud Full Documentation Context

SIMcloud is Freepaid's web platform for prepaid airtime, prepaid data, prepaid electricity, SIM fleet management, SMS, and related VAS workflows for South African businesses. The site positions SIMcloud as South Africa's biggest prepaid airtime platform and describes it as a wallet-based operations tool for organisations that need to recharge one number or many numbers, manage recurring activity, track spend and failures, and retrieve reports and invoices.

SIMcloud is presented as a business operations platform rather than a casual consumer top-up site. The homepage targets companies and institutions that manage employee fleets, schools, transport and logistics operations, IoT and telemetry deployments, remote monitoring devices, field teams, and marketing or loyalty campaigns that use airtime or data as rewards.

The core SIMcloud promise is centralised control. The public copy repeatedly highlights one secure login, wallet-based funding, support for major South African networks, 24/7 recharge availability, instant transaction status reporting, automatic or immediate reversal when a recharge fails, no monthly fees, no setup fees, no hidden admin fees, and online access to tax invoices and other reports.

## Product Overview

The homepage describes SIMcloud as a platform to recharge and manage a SIM card fleet anywhere and any time. It says users can manage, recharge, and track spending on their SIM cards through a single secure login. It also says the platform is free to use, with no monthly fees or hidden costs, and that it supports all major South African networks.

The homepage explains the operating flow in plain language:
- register online for free
- receive access to a SIMcloud wallet and management portal
- top up the wallet by depositing into the SIMcloud bank account using the registered cell number as the unique reference
- complete verification if needed on the first payment
- capture and organise mobile numbers into operational lists
- recharge a list or individual numbers with one action
- track spending per number and retrieve monthly tax invoices and reports

The public use cases listed on the site include:
- business phone fleets for employees or field agents
- schools that need to keep staff and students connected
- fleet and vehicle management where drivers need airtime or data
- telemetry and IoT SIMs used in monitoring devices
- promotions, loyalty rewards, surveys, and competitions that issue airtime or data rewards

The site also presents SIMcloud as part of Freepaid's wider prepaid product ecosystem. It says Freepaid has been providing airtime solutions to South African businesses since 2003 and that SIMcloud is built on proven Freepaid infrastructure.

## Funding And Billing

SIMcloud is wallet-based. The documentation and help pages make it clear that a positive balance must appear on the account before orders can be placed. The legal page says the availability of the service depends on a sufficient positive balance in the account holder's wallet.

The payment guidance on the site is operationally specific:
- payments are made to FREEPAID (PTY) LTD
- the banking page uses FNB Tygerberg details
- users are told to put only their cell number in the payment reference
- FNB EFT payments can credit automatically and immediately when the correct cell number is used
- EFT payments from other banks can take longer to reflect
- deposits above R150 are preferred for automatic capture
- users are asked not to make two identical-value payments within seven days, and to vary the second amount slightly if needed
- cash deposits can attract bank charges

The pricing and legal pages also state:
- airtime is sold at face value
- airtime values can be loaded in whole rands from R2 to R999
- data bundles are listed publicly
- pricing is described as ICASA-approved or standard market pricing
- there are no SIMcloud transaction fees, no admin fees, no setup fees, and no monthly fees
- failed orders are not charged for and are refunded or reversed to the wallet

## Registration And Login

The registration flow creates a SIMcloud account tied to the Freepaid backend. The public registration page collects the following:
- optional ID number
- first name
- last name
- cell number
- email address
- password and password confirmation
- optional business name
- optional business address
- optional business registration number
- optional VAT number

The registration flow performs a backend Freepaid registration call before creating the local user record. After a successful registration it sends internal notification emails, sends a welcome SMS, and redirects the new user to the login page.

The login page uses a cell number and password. On successful login the session is populated with:
- user ID
- Freepaid username
- business details
- VAT and address details
- role
- cell number
- first and last name
- last known balance
- email address
- SIM Manager activation flags and cost information
- distributor-site and network configuration

After login, the system checks the user's balance and then redirects to the main dashboard.

## Dashboard And Main Logged-In Workflows

The dashboard is the main operational page after login. It shows the user's last known balance, an update balance action, a wallet top-up link, and shortcut cards for the main product areas.

The main dashboard product areas are:
- Data Recharge
- Airtime Recharge
- Bulk Recharge
- Electricity
- Send SMS
- Bulk SMS
- Affiliate Dashboard
- Knowledge Base

The dashboard also displays recent airtime orders, recent data orders, and failed orders. The failed-order table notes that users are not billed for failed orders and suggests using the network lookup tool to confirm the number is on the correct network.

## Airtime And Data Recharge

The tutorial explains the single recharge workflow clearly.

For a single airtime recharge, the user:
1. enters the mobile number
2. selects the network
3. enters an amount between R2 and R999
4. enters a reference for the order

For a single data recharge, the user:
1. enters the mobile number
2. selects the network
3. selects a data bundle from the dropdown menus
4. enters a custom reference for the order

The public and logged-in pages both reinforce that SIMcloud supports multiple South African networks and is designed to make single and fleet recharges operationally simple.

## Bulk Recharge And CSV Import

SIMcloud supports bulk recharge in two main ways: recharging a saved list and importing a CSV file.

The bulk recharge tutorial says users can:
1. download the CSV template
2. fill in the spreadsheet with mixed networks, values, and recharge types
3. save the file as CSV
4. go to the Bulk Recharge page
5. import the CSV
6. name the file and upload it
7. confirm and submit the batch

The documented CSV fields are:
- `msisdn`: mobile number, starting with zero
- `network`: network name, for example `vodacom` for airtime or `pd-vodacom` for data
- `value`: recharge amount, using `2-999` for airtime or the exact sell value for data
- `reference`: a unique reference for each recharge

The CSV import page also guides users through exporting an Excel workbook to CSV and offers conversion help via `techsupport@freepaid.co.za`.

## Recurring Orders

SIMcloud supports scheduled recurring recharges. The tutorial explains that recurring orders are useful when users need to keep employees, customers, or family members supplied with regular airtime or data.

The recurring order setup described in the tutorial is:
1. go to either the Airtime Recharge or Data Bundle page
2. fill in the recharge details
3. click "Schedule for later"
4. choose the auto-repeat option
5. select a frequency, such as every 7 or 30 days
6. choose an end date if needed
7. confirm and submit

The recurring orders page then lets users review active recurring orders, review past recurring orders, and delete recurring orders they want to stop.

## Prepaid Electricity

SIMcloud includes a prepaid electricity workflow inside the logged-in product set. The electricity page asks for:
- meter number
- amount
- customer reference
- recipient mobile number

The page copy explains that once the order is placed, the user is redirected to the electricity history page where voucher details and transaction information appear. The billing flow in code and UI terms is wallet-based and linked to the general reporting and billing model of the platform.

## SMS Products

SIMcloud includes both single SMS and bulk SMS workflows.

The single SMS page allows the user to:
- enter one recipient
- type a message
- optionally use an existing template
- manage saved templates

The SMS billing guidance on the page states:
- 1 SMS costs R0.23 including VAT
- 0 to 160 characters counts as 1 SMS
- 161 to 306 characters counts as 2 SMSes
- 307 to 459 characters counts as 3 SMSes
- messages longer than 160 characters are concatenated and displayed as one message on the phone

The bulk SMS page uses a CSV format with the columns:
- `recipient`
- `message`

The bulk SMS flow validates phone numbers, sanitises message content, enforces a maximum message length, and sends the user to a confirmation step before the messages are submitted.

The SMS API Management page gives logged-in users a way to generate and manage API tokens for application-driven SMS sending.

## API, OAuth, And MCP

SIMcloud provides a documented REST API and an OAuth-protected MCP server for authenticated, account-specific workflows. The MCP server is the preferred connection path for AI assistants that support MCP and OAuth. Direct API integrations should use the OpenAPI contract as the source of truth for the current request and response formats.

The primary integration resources are:
- MCP endpoint: `https://simcloud.co.za/api/mcp.php`
- OAuth protected-resource metadata: `https://simcloud.co.za/.well-known/oauth-protected-resource`
- OAuth authorization-server metadata: `https://simcloud.co.za/.well-known/oauth-authorization-server`
- OpenAPI contract: `https://simcloud.co.za/api/openapi.yaml`
- Integration guide: `https://simcloud.co.za/api/ai.html`

Users authenticate with their own SIMcloud account. Tool calls use that connected user's own wallet and permissions; an assistant must not assume it can use a shared account or token. The OAuth scope is `api`, and the authorization flow requires PKCE using `S256`.

The MCP capabilities cover wallet balance, mobile-network lookup, SMS send and status checks, airtime and data orders and status checks, VAS product and order workflows, and prepaid-electricity meter checks, purchases, and status checks. Current balances, available data products, VAS products, network results, meter support, and order status are live data: retrieve them from authenticated tools or API endpoints rather than inferring them from this document.

For a wallet-funded or externally delivered action, an assistant or integration should:
1. confirm the connected account, final recipient or meter, network or product, rand amount, and reference
2. look up an unknown mobile network before airtime, data, or SMS; list current data or VAS products before creating the corresponding order; and check an electricity meter before buying electricity
3. submit the action once
4. retrieve its status using the returned identifier if the response is ambiguous or confirmation is required

Do not automatically retry an ambiguous create request. An order or message should not be described as successful until SIMcloud returns its status.

## SIM Manager And SuperSIM

The broader application includes a dedicated SIM Manager area for businesses that need to manage a fleet of SIM cards in more detail. The project structure and linked pages indicate functionality around:
- managed SIM lists
- balance lookups
- alert thresholds
- SIM references
- billing
- reporting
- bulk SIM imports

The site also includes SuperSIM-specific flows:
- SuperSIM recharge
- SuperSIM reporting
- a SuperSIM self-help portal for activation requests, SIM swaps, suspensions, cancellations, reference changes, and additional email management

## Reports, Failures, And Invoices

The tutorial distinguishes between different reporting paths.

For single recharges, orders are executed immediately and copied to the `orders` table. SIMcloud then checks the status regularly and updates the dashboard.

For bulk recharges, the tutorial points users to report pages for different failure and success cases, including:
- failed uploaded orders
- failed transactions
- successful transactions
- transaction search

The site emphasises that failed orders are not billed and that failed value is reversed to the wallet.

Tax invoice guidance appears in both the tutorial and the dedicated invoice page:
- tax invoices are generated on the first day of each month
- users retrieve them from `services.freepaid.co.za` using their SIMcloud credentials
- other airtime reports are also available there
- a pro-forma invoice can be requested from `accounts@freepaid.co.za` or generated through the site's pro-forma flow

The dedicated invoice page also says generated pro-forma invoices are emailed to the user with a PDF attachment and a unique `FP-XXXX` style reference number.

## Legal And Operational Notes

The legal page states:
- registration and payment amount to agreement to purchase airtime or data at the pricing offered on the site
- the operating system and technical information may change at the discretion of the networks or the vendor
- the airtime delivery platform is proprietary software
- there is no registration fee and no additional platform charge for using the service
- the service depends on sufficient positive wallet balance
- failed orders are refunded into the wallet
- payments are non-refundable and can only be redeemed as airtime or data
- the company will not share personal details except where compelled by law
- the user may be contacted by email in connection with airtime services
- the company disclaims liability for direct, indirect, incidental, consequential, and similar damage once a valid recharge has been requested

The legal page also says affiliate participants are subject to separate affiliate terms and conditions.

## Related And Adjacent Products

The homepage includes a Universal Airtime Vouchers section promoting `allnetairtime.co.za`. That product is described as a related Freepaid property where users can generate cross-network airtime vouchers and PINs for use in competitions, staff rewards, promotions, customer giveaways, and similar reward-style scenarios.

This related product matters because SIMcloud is positioned not only as a recharge tool but as part of a wider prepaid and VAS ecosystem that includes:
- network lookup
- SMS tools
- affiliate/referral features
- reward and voucher use cases

## Interpretation Notes For Retrieval

If a user asks what SIMcloud does, the best short answer is that it is a South African business platform for funding a wallet and then buying prepaid airtime, data, electricity, SMS, and related services for one number or many numbers, with reporting and billing support built in.

If a user asks how to use SIMcloud, the core answer is:
1. register
2. fund the wallet by EFT using the cell number as reference
3. wait for balance to reflect
4. place single, bulk, recurring, electricity, or SMS transactions
5. review outcomes on the dashboard and in the reporting pages

If a user asks about SIMcloud's strongest differentiators, the clearest answers from the site are:
- bulk and fleet capability
- centralised wallet-based control
- multi-network support
- 24/7 operation
- instant status reporting
- failed-order reversal
- invoice and reporting support

If a user asks about invoices, reports, or funding, the most relevant pages are:
- `how_to_pay.php`
- `tax-invoices.php`
- `tutorial.php`
- `dashboard.php`

If a user asks about messaging or VAS, the most relevant pages are:
- `send_sms.php`
- `bulk_sms.php`
- `sms_api_management.php`
- `public_lookup_tool.php`
- the Universal Airtime Vouchers section linked to `allnetairtime.co.za`