API Docs / Electricity

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

  1. Optionally check a meter number with GET before placing an order.
  2. Submit a purchase request with POST.
  3. SIMcloud submits the request to the municipality and stores the order locally.
  4. Poll the same endpoint with GET until the order status changes from pending to a final status.
  5. When the order completes successfully, the response includes the voucher PIN details.

Endpoints

1. Check Meter Support

Validate a prepaid electricity meter number before placing an order.

GET

Query Parameters

Parameter Type Required Description
meter_number string Yes Meter number to validate. Spaces and hyphens are removed before checking.

Example Request

GET https://simcloud.co.za/api/electricity.php?meter_number=01234567890

Supported Meter Response

{
    "status": "success",
    "message": "We support this meter.",
    "meter_number": "01234567890",
    "supported": true,
    "provider": "City of Ekurhuleni IMMS",
    "query_result": 0,
    "result_message": "Success: City of Ekurhuleni IMMS",
    "supplier_response": {
        "queryResult": 0,
        "resultMessage": "Success: City of Ekurhuleni IMMS"
    }
}

Unsupported Meter Response

{
    "status": "unsupported",
    "message": "Meter not supported",
    "meter_number": "01234567890",
    "supported": false,
    "provider": null,
    "query_result": 2,
    "result_message": "Meter not supported",
    "supplier_response": {
        "queryResult": 2,
        "resultMessage": "Meter not supported"
    }
}

Supplier Validation Error Response

When the supplier responds with an internal validation error, retry later. Do not treat the meter as unsupported.

{
    "status": "unknown",
    "message": "Could not validate — supplier internal error",
    "meter_number": "01234567890",
    "supported": null,
    "provider": null,
    "query_result": 2,
    "result_message": "Internal Error",
    "supplier_response": {
        "queryResult": 2,
        "resultMessage": "Internal Error"
    }
}

2. 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.
send_sms boolean No Set to false to prevent the SIMcloud completion SMS from being sent for this order. Defaults to true.
sms_company_name string No Optional custom company name to use in the SIMcloud completion SMS.

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

These SMS options apply only to the SIMcloud Electricity API and only affect the SIMcloud completion SMS sent after a successful order.

Example Request

{
    "meter_number": "01234567890",
    "amount": 150.00,
    "client_reference": "INV-10045",
    "recipient": "0821234567",
    "send_sms": true,
    "sms_company_name": "acme power"
}

Example Request With SMS Disabled

{
    "meter_number": "01234567890",
    "amount": 150.00,
    "client_reference": "INV-10046",
    "recipient": "0821234567",
    "send_sms": false
}

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",
    "send_sms": true,
    "sms_company_name": "acme power",
    "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
}

3. 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

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