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.
• monetaryFields — the receipt paths that hold amounts, returned in cents. See Monetary Fields.

{
  "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.
• Convert monetary values for display. Monetary receipt fields are returned in cents. Use monetaryFields from the category metadata to know which values to divide by 100, and show them in ZAR (R). See Monetary Fields.

---

Last updated: April 2026