Receipt Configuration

When a purchase succeeds, the API returns a receipt object. The shape of this object varies by product category — an airtime receipt looks different from an electricity token receipt.

To render the right receipt for the right product, use the category metadata.

Fetch Category Metadata

GET /api/v1/products/categories/{categoryId}/fields

The response contains both:

• fields — input fields the user must supply to make a purchase.
• receiptFields — the keys that will appear in the receipt object on success, in the order you should display them.

{
  "fields": [
    { "name": "meterNumber", "type": "string", "required": true }
  ],
  "receiptFields": [
    "receipt.token",
    "receipt.units",
    "receipt.unitType",
    "receipt.taxAmount",
    "receipt.amount",
    "receipt.meterNumber"
  ]
}

Field Path Notation

receiptFields uses dot notation rooted at the response object. Some products produce arrays — in that case, you'll see bracket notation:

Path	Reads from response
receipt.amount	response.receipt.amount
receipt.token	response.receipt.token
receipt.items[0].pin	First element's pin in an items array

Example: Electricity Receipt

Given this purchase response:

{
  "transactionId": "bdf82429-...",
  "responseCode": "0",
  "successful": true,
  "receipt": {
    "token": "12341234123412341234",
    "units": 100,
    "unitType": "kWh",
    "taxAmount": 18.42,
    "amount": 3000,
    "meterNumber": "0008958825192"
  }
}

And receiptFields from the category metadata, you can render:

Token:        12341234123412341234
Units:        100
Unit Type:    kWh
Tax Amount:   R18.42
Amount:       R3000
Meter Number: 0008958825192

Example: Voucher Receipt

Voucher receipts typically include a pin, serialNumber, and expiryDate. The category metadata for vouchers will list these in the recommended display order.

Best Practice

• Don't hard-code receipt fields per product. Use receiptFields from category metadata so new products and field changes don't require a client release.
• Render unknown keys gracefully. Skip them rather than failing.
• Format monetary values with currency. Always ZAR (R) unless your category metadata indicates otherwise.

---

Last updated: April 2026