Purchase / Vend Token

Request

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

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

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

** To claim FBE, you need to put an amount of 0 and the system will check if the customer is eligible for FBE. If they are, it will vend the FBE amount to the customer. **

Security

ApiKeyAuth

Bodyapplication/jsonrequired

meterNumberstringrequired

Example:"04235758721"

municipalitystring(Municipality)required

Municipality identifier. Municipalities ending in _prepaid support token vending

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": { … }
  }
}