Response Formats

All Pagamio VAS API responses follow a consistent envelope. Knowing this shape lets you write a single response handler in your client.

Standard Fields

Field	Type	Description
responseCode	string	Machine-readable code. "0" indicates success. Any other value indicates failure.
responseMessage	string	Human-readable explanation of the result.
successful	boolean	true for a successful terminal result, false otherwise.
transactionId	string	Unique reference for the transaction. Use this for status polling and reconciliation.
responseDateTime	string	ISO-8601 timestamp of when the response was produced.
receipt	object	Present on successful purchases. Shape depends on the product type.
data	object	Present on lookup, query, and read endpoints. Shape depends on the endpoint.

Successful Purchase

{
  "transactionId": "bdf82429-9ab5-4f1a-bb9a-e469f4f05f05",
  "responseCode": "0",
  "responseMessage": "Purchase successful",
  "responseDateTime": "2026-04-21T12:57:51.831786006",
  "successful": true,
  "receipt": {
    "amount": 50.0,
    "reference": "bdf82429-9ab5-4f1a-bb9a-e469f4f05f05"
  }
}

Failed Purchase

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

Receipt Shape

The receipt object varies by product category. Common fields include:

• All products: amount, reference
• Airtime / Data / SMS: pin (if pinned), serialNumber
• Vouchers: pin, serialNumber, expiryDate
• Electricity: token, units, unitType, meterNumber, taxAmount, aggregator

To know exactly which fields to display for a given category, fetch the category metadata. See GET /products/categories/{categoryId}/fields and Receipt Configuration.

Paginated Responses

List endpoints return a paged envelope:

{
  "content": [ /* array of items */ ],
  "page": 0,
  "size": 20,
  "totalElements": 137,
  "totalPages": 7
}

See Pagination for details.

Error Responses

Both 4xx and 5xx responses use the same envelope as a failed purchase. The responseCode carries the business error code (see Error Code Reference) and the HTTP status reflects the class of error (see HTTP Status Codes).

---

Last updated: April 2026