How to Integrate a Prepaid Electricity API in South Africa

The SIMcloud Electricity API lets an application check meter support, submit a prepaid electricity order and poll until the municipality returns a final result. A successful final response contains the recharge PIN information; the initial order response may not.

Because electricity purchases are value-bearing and normally irreversible after success, the integration must validate first, persist identifiers and never assume that a timeout means the order failed.

Use the correct electricity workflow

1. Validate the meter format and purchase amount locally.
2. Call the meter-support endpoint.
3. Show the returned provider and require confirmation where appropriate.
4. Check account wallet readiness.
5. Create a unique local order and client reference.
6. POST the electricity purchase once.
7. Persist the returned SIMcloud and municipality identifiers.
8. Poll to success, failed or cancelled.
9. Protect and deliver the returned PIN details.

Check whether the meter is supported

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

Spaces and hyphens are removed before checking. A successful response includes supported: true and the detected provider. An unsupported result includes supported: false.

Submit the electricity order

The documented request uses meter_number, amount, client_reference and recipient. The current amount range is R50 to R1,000. Recheck the live API documentation before production deployment.

POST https://simcloud.co.za/api/electricity.php
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "meter_number": "01234567890",
  "amount": 150.00,
  "client_reference": "PROPERTY-44-JULY",
  "recipient": "0821234567",
  "send_sms": true,
  "sms_company_name": "acme power"
}

send_sms defaults to true and controls the SIMcloud completion SMS for this Electricity API order. Set it to false only when your application has an approved alternative delivery process. The optional company name applies to that completion SMS.

HTTP 201 returns fields including:

• order_id
• stored and submitted client references
• order_reference_id
• normalised meter and recipient
• amount, electricity amount and fee
• processing and billing states

Persist these immediately. The returned client reference may have a timestamp appended, so retain both your local reference and the value returned by SIMcloud.

Poll for the municipality result

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

You may query by internal order ID, stored client reference or municipality order reference. Use the exact identifier returned by the POST response.

Protect the recharge PIN

The successful response can include transaction details and one or more PIN entries with description, PIN and units. Exclude full PINs from ordinary logs, analytics and support exports. Store them in the protected order record and reveal them only to the authorised user or delivery service.

Handle failures by type

• 400: correct invalid parameters or insufficient balance; do not retry unchanged.
• 401: stop processing and fix API authentication.
• 404: check account ownership and the exact returned identifier.
• 502: municipality request failed; reconcile the existing local request before resubmitting.
• 503: service is temporarily unavailable; do not accept value without a controlled queued/retry process.
• Timeout: outcome may be unknown. Investigate by reference before another purchase.

Production controls

• Meter stored and transmitted as a string.
• Meter support checked before purchase.
• Recipient and amount confirmed.
• Unique local reference created.
• POST protected from double submission.
• Returned identifiers persisted transactionally.
• Polling performed by a background worker.
• PINs excluded from logs.
• Successful, failed and cancelled results reconciled separately.

Frequently asked questions