Get Product Categories

This endpoint retrieves the list of available product categories in the Pagamio VAS system. Each category includes metadata that defines the required fields for transactions and the receipt structure.

---

Path: POST BASE_URL/products/categories

Authorization: Bearer <YOUR_BEARER_TOKEN>

---

Description

• Fetches all active product categories available to the merchant/sub-merchant.
• The meta field contains JSON that specifies required input fields for purchase requests and the receipt structure.

---

Response Structure

Responses are returned in JSON array format. Each category object includes the following fields:

Field Name	Type	Description
id	number	Unique identifier of the category
createdById	number	ID of the user who created the category
lastModifiedById	number	ID of the user who last modified the category
createdDate	string (ISO)	Timestamp when the category was created
lastModifiedDate	string (ISO)	Timestamp when the category was last updated
state	number	Category state (1 = active, 0 = inactive)
name	string	Name of the category
imageUrl	string	URL of the category image
orderOfAppearance	number	Position of category when displaying in the UI
parentId	number/null	ID of parent category, if applicable; null for top-level categories
meta	string (JSON)	JSON string describing transaction input fields (fields) and receipt fields (receiptFields)

---

Sample Response

[
  {
    "id": 2000,
    "createdById": 1000,
    "lastModifiedById": 1000,
    "createdDate": "2025-08-01T05:12:32.269743",
    "lastModifiedDate": "2025-09-07T04:19:29.161137",
    "state": 1,
    "name": "SMS",
    "imageUrl": "https://pagamio-assets.ams3.digitaloceanspaces.com/vas-uat/1756973529660-1756973526085_5u6t2x.png",
    "orderOfAppearance": 10,
    "parentId": null,
    "meta": "{\"fields\":[{\"name\":\"amount\",\"type\":\"number\",\"required\":true},{\"name\":\"mobileNumber\",\"type\":\"string\",\"required\":true},{\"name\":\"paymentMethod\",\"type\":\"string\",\"required\":true}],\"receiptFields\":[\"rechargeDetails.rechargeType\",\"rechargeDetails.callCentre\",\"rechargeDetails.rechargeVendor\",\"amount\",\"reference\"]}"
  },
  {
    "id": 1001,
    "createdById": 1000,
    "lastModifiedById": 1000,
    "createdDate": "2025-07-14T09:11:18.129716",
    "lastModifiedDate": "2025-09-07T04:19:44.555666",
    "state": 1,
    "name": "Airtime",
    "imageUrl": "https://pagamio-assets.ams3.digitaloceanspaces.com/vas-uat/1756973467304-1756973463756_1q3x24.png",
    "orderOfAppearance": 1,
    "parentId": null,
    "meta": "{\"fields\":[{\"name\":\"amount\",\"type\":\"number\",\"required\":true},{\"name\":\"mobileNumber\",\"type\":\"string\",\"required\":true},{\"name\":\"paymentMethod\",\"type\":\"string\",\"required\":true}],\"receiptFields\":[\"rechargeDetails.rechargeType\",\"rechargeDetails.callCentre\",\"rechargeDetails.rechargeVendor\",\"amount\"]}"
  }
]

---

Notes on meta Field

• fields: Specifies the input parameters required to create a purchase transaction for this category.
  • name – field name
  • type – data type (string, number, etc.)
  • required – boolean indicating if the field is mandatory
• receiptFields: Defines which response fields will appear in the transaction receipt.

⚠️ The meta field is returned as a JSON string. It must be parsed into a JSON object before use.

---

Best Practices

1. Always include the Authorization Bearer token.
2. Use the meta.fields to dynamically generate request payloads for purchases.
3. The order of categories in the UI should follow orderOfAppearance.
4. For sub-categories, check the parentId field to determine hierarchy.
5. Validate all required fields before making a purchase request to avoid errors.

---

Last updated: October 2025