Request & Response Format

This section describes the standard request and response formats used across the Pagamio VAS API. It includes examples, content types, common headers, and best practices.

---

1. Request Structure

All API requests must be made using HTTPS and include the required headers.

HTTP Method

• Most endpoints use POST or GET

Common Headers

Header Name	Description	Example
Authorization	Bearer token obtained from /auth/token	Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type	Content type of the request body	application/json
Accept	Expected response format	application/json

Request Body

Requests with a body (e.g., POST) must be in JSON format.

1. Normal Products / Services

{
  "productCode": "AIR-VOD-001",
  "amount": 10.00,
  "mobileNumber": "+27821234567",
  "paymentMethod": "cash",
  "channelId": "YOUR_CHANNEL_ID"
}

---

2. Electricity Payments

Electricity payments require an additional meterNumber field:

{
  "productCode": "ELE-FLS-001",
  "amount": 30,
  "mobileNumber": "+27821234567",
  "paymentMethod": "cash",
  "channelId": "F5YZP7",
  "meterNumber": "0008958825192"
}

⚠️ All field names are case-sensitive. Ensure meterNumber is provided for electricity products.

---

2. Response Structure

All responses are returned in JSON format with a consistent structure.

Standard Response Fields

Field Name	Description	Example
responseCode	API status code (0 = success, non-zero = error)	"0"
responseMessage	Human-readable message	"Purchase successful"
responseDateTime	ISO 8601 timestamp of response	"2025-10-21T10:03:45.698Z"
transactionId	Unique ID for the request/transaction	"4f59984d-9d97-4f0a-8510-26521f52d941"
receipt	Payload specific to the endpoint	{ "amount": 3000, "status": "SUCCESS" }
successful	Boolean indicating success/failure	true

Example Response

{
  "transactionId": "4f59984d-9d97-4f0a-8510-26521f52d941",
  "responseCode": "0",
  "responseMessage": "Purchase successful",
  "responseDateTime": "2025-10-21T10:03:45.698Z",
  "successful": true,
  "data": {
    "rechargeType": "PINLESS",
    "callCentre": "083173",
    "rechargeVendor": "AirtimeStub",
    "amount": 3000,
    "aggregator": "FLASH"
  }
}

Example Response for electricity purchase

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

---

3. Content Types

• Request: application/json
• Response: application/json
• Ensure the correct Content-Type header is sent for all requests that include a body.

---

4. Common Headers & Notes

• Authorization: Required for all endpoints except /auth/token and /auth/login
• Content-Type: Must be application/json for POST requests
• Accept: Set to application/json to ensure proper response formatting

⚠️ Always validate the responseCode in the response to confirm success before processing data.

---

5. Best Practices

1. Always use HTTPS to ensure data security.
2. Log transactionId for each request to help with support and troubleshooting.
3. Handle errors gracefully: Check both responseCode and successful fields.
4. Implement retries for transient network failures, but avoid duplicate transactions.
5. Time zone consistency: All timestamps are in ISO 8601 format, using South African Standard Time (SAST, UTC+2).

---