Skip to content
/
Purchase / Vend Token / P...

Purchase / Vend Token / Pay Bills

Request

Vends an electricity token (prepaid) or marks a payment against a postpaid running balance.

  • Prepaid (tshwane_prepaid, mogale_prepaid, zeerust_prepaid, ngwathe_prepaid): returns a token string the customer enters into their meter.

  • Postpaid (mogale_postpaid, tshwane_postpaid): returns a receipt URL proving bill offset.

Use the idempotency field to safely retry failed requests without risk of duplicate vends.

Postpaid bill payments: if you already know you're paying a postpaid municipal account, prefer the dedicated Bills/Purchase and Bills/ConfirmCustomer endpoints — they identify the account by accountNumber rather than meterNumber and drop fields that only apply to prepaid vending.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
meterNumberstringrequired
Example:"04235758721"
municipalitystring(Municipality)required

Municipality identifier. Municipalities ending in _prepaid support token vending; Municipalities ending in _postpaid supports postpaid bill payments.

Enum:"tshwane_prepaid""zeerust_prepaid""mogale_prepaid""ngwathe_prepaid""mogale_postpaid""tshwane_postpaid"
amountnumberrequired
Example:400
methodstringrequired
Enum:"cash""card"
Example:"cash"
idempotencystring

Unique string to prevent duplicate vends. A second request with the same value will not result in a second transaction.

Example:"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
curl -i -X POST \
  https://docs.amabills.co.za/_mock/openapi/v2/Electricity/Purchase \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "meterNumber": "04235758721",
    "municipality": "zeerust_prepaid",
    "amount": 400,
    "method": "cash",
    "idempotency": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Responses

Purchase response.

Bodyapplication/json
successboolean

true - action successful, result is in data. false - error occurred, details are in error and errorNo.

Example:true
dataobject or null(PurchaseElectricityResult)

Result payload. null when success is false.

errorstring or null

Human-readable error message. null when success is true.

Example:"999 - Internal server error"
errorNointeger or null

Error code. null when success is true.

Example:999
Response
{
  "success": true,
  "data": {
    "name": "MR. A J KWINDA",
    "amount": 50,
    "meter": "81114926223",
    "date": "22 Mar 2026 3:24:11 PM",
    "timestamp": 1774193051166,
    "token": "        City of Tshwane\n        ---------------\nReceipt No.: 109707/29\n...",
    "tokenCount": 1,
    "units": 2.9,
    "receipt": null,
    "municipality": "tshwane_prepaid",
    "mode": 0,
    "details": { … },
    "meterDetails": { … }
  }
}