Purchase

This is the main endpoint of the API and allows purchase of all types of products, from different categories and vendors.

Description: Process a VAS purchase transaction

Path: POST /purchase

Authentication Required: ✅

All requests must include a valid Bearer token in the Authorization header:

Authorization: Bearer <YOUR_BEARER_TOKEN>

Request Body:

{
  "productCode": "AIR-VOD-001",
  "amount": 50.0,
  "mobileNumber": "+27821234567",
  "paymentMethod": "cash",
  "channelId": "YOUR_CHANNEL_ID",
  "meterNumber": "0008958825192"   // For Electricity Products
}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "transactionId": "b9871532-3252-4920-b99e-081dc1488494",
    "status": "COMPLETED",
    "responseCode": 0,
    "responseMessage": "Purchase successful",
    "receipt": {
      "amount": 50.0,
      "reference": "b9871532-3252-4920-b99e-081dc1488494",
      "pin": "1234567890", // If applicable
      "serialNumber": "SN123456",
      "expiryDate": "2025-12-31"
    }
  }
}

Electricity Products

{
    "transactionId": "bdf82429-9ab5-4f1a-bb9a-e469f4f05f05",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-10-21T12:57:51.831786006",
    "successful": true,
    "receipt": {
        "unitType": "kWh",
        "units": 100,
        "transactionNumber": 5346883805,
        "receiptNumber": "16252/861882",
        "taxAmount": 18.42,
        "exclusiveAmount": 150,
        "name": "Test Utility",
        "address": "27 Meteren Crescent Avondale",
        "meterNumber": "0008958825192",
        "token": "12341234123412341234",
        "tokenDescription": "FBE Token",
        "amount": 3000,
        "aggregator": "FLASH"
    }
}

Error Response (400 Bad Request):

{
    "responseCode": "1103",
    "responseMessage": "Insufficient balance. Available: R0.00"
}

---

Last updated: October 2025