Electricity API Documentation

Base URL

https://simcloud.co.za/api/electricity.php

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

How It Works

Submit a purchase request with POST.
SIMcloud submits the request to the municipality and stores the order locally.
Poll the same endpoint with GET until the order status changes from pending to a final status.
When the order completes successfully, the response includes the voucher PIN details.

Endpoints

1. Place Electricity Order

Create a new prepaid electricity purchase request.

POST Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
meter_number	string	Yes	Meter number to recharge.
amount	number	Yes	Total customer amount in rand. Must be between 50 and 1000.
client_reference	string	Yes	Your reference for the order. SIMcloud appends a timestamp before storing/submitting it.
recipient	string	Yes	South African mobile number that should receive the PIN SMS.

The API also accepts the existing field names deviceId, electricity_order_reference and smsRecipientMsisdn for compatibility.

Example Request

{
    "meter_number": "01234567890",
    "amount": 150.00,
    "client_reference": "INV-10045",
    "recipient": "0821234567"
}

Success Response

{
    "status": "success",
    "message": "Electricity order accepted",
    "order_id": 415,
    "client_reference": "INV-10045_1763270400",
    "submitted_reference": "INV-10045",
    "order_reference_id": 987654321,
    "meter_number": "01234567890",
    "recipient": "27821234567",
    "amount": 150,
    "electricity_amount": 145.63,
    "fee": 4.37,
    "process_status": "Pending",
    "billing_status": "pending",
    "timestamp": "2026-04-16 14:30:00"
}

Insufficient Balance Response

{
    "status": "error",
    "message": "Insufficient balance. Please top up your account.",
    "required_balance": 150,
    "available_balance": 120
}

2. Query Electricity Order

Poll an existing electricity order by internal order ID, SIMcloud client reference, or municipality order reference.

GET

Query Parameters

Parameter	Type	Required	Description
order_id	integer	No	SIMcloud electricity order ID returned by the POST request.
client_reference	string	No	The stored client reference returned by the POST request.
order_reference_id	integer	No	Municipality order reference returned by the POST request.

At least one of the three query parameters is required.

Only orders that belong to the authenticated account can be queried.

Example Request

GET https://simcloud.co.za/api/electricity.php?order_id=415

Pending Response

{
    "status": "pending",
    "message": "Voucher details are not available yet. Please allow a few moments for the Municipality to provide the voucher details"
}

Successful Response

{
    "status": "success",
    "message": "This electricity order has been processed successfully.",
    "transaction_details": {
        "reference": "1209121380",
        "amount": "R53.40",
        "recipient": "27676101188",
        "meter_number": "07148231520",
        "network": "Electricity-Municipalities",
        "date": "2026-03-30 21:19:11",
        "utility": "Prepay Metering"
    },
    "recharge_pin_information": [
        {
            "description": "PURCHASE",
            "pin": "0092 0215 1214 3650 1304",
            "units": "13.70"
        }
    ]
}

Statuses

pending: Order has been submitted but is not final yet.
success: Order completed successfully and voucher details are available.
failed: The municipality returned a failed status.
cancelled: The municipality returned a cancelled status.

Error Codes

Code	Description
400	Bad Request (missing or invalid parameters)
401	Unauthorized (invalid or missing token)
404	Order not found
502	Municipality request failed
503	Electricity service temporarily unavailable