Get Transactions

This endpoint retrieves transaction records for a specific merchant or sub-merchant. It supports pagination, filtering, and export of all transactions.

---

Path: POST BASE_URL/transactions

Authorization: Bearer <YOUR_BEARER_TOKEN>

---

Required Query Parameters

Parameter	Description	Example
userType	Type of user: MERCHANT or SUB_MERCHANT	MERCHANT
userTypeId	Unique ID of the merchant/sub-merchant (obtained from login response)	Zd5Euw0OAyZQU1MUgHdwETatZFV_qtNw7yJzZyA

---

Optional Query Parameters

Parameter	Description	Example
categoryName	Filter transactions by product category	Airtime
brandName	Filter transactions by brand	Vodacom
aggregatorName	Filter transactions by aggregator	FLASH
status	Filter by transaction status (COMPLETED=0, PENDING=1, PROCESSING=2, FAILED=3)	0
keyWord	Search transactions by productName or productShortName	Airtime Direct
exportAll	Return all transactions in a single JSON array (ignores pagination). Default is false	true
page	Page number (if exportAll=false)	1
size	Number of items per page (if exportAll=false)	20

⚠️ exportAll=true is intended for exporting data. If set, pagination parameters (page, size) are ignored.

---

Response Structure

Responses are returned in JSON format. When exportAll=false, results are paginated.

Paginated Response Example

{
  "content": [
    {
      "id": "WypJNrMGBKezxQTdtscWadoCiNyDD3pBzeFCYRnnzZjQaw",
      "status": {
        "code": 0,
        "label": "Successful",
        "description": "Item has been processed successfully",
        "badgeColor": "green"
      },
      "productName": "R10 - R3500 FLASH Group Electricity",
      "productShortName": "FLASH Group",
      "quantity": 1,
      "price": 30.0000,
      "totalAmount": 30.0000,
      "transactionId": "bdf82429-9ab5-4f1a-bb9a-e469f4f05f05",
      "responseDate": "2025-10-21T12:57:51.831899",
      "productImage": "https://pagamio-assets.ams3.digitaloceanspaces.com/vas-uat/1756442263930-1756442259265_61l654.jpg",
      "brandName": "FLASH Group",
      "categoryName": "Electricity",
      "channelName": "Default",
      "merchantName": "Eudson Bambo",
      "partnerName": "Zapper",
      "aggregatorName": "FLASH"
    }
  ],
  "pageable": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 3,
    "totalElements": 55
  }
}

Export All Response Example

When exportAll=true, all transactions are returned as a single JSON array:

[
  {
    "id": "WypJNrMGBKezxQTdtscWadoCiNyDD3pBzeFCYRnnzZjQaw",
    "status": {
      "code": 0,
      "label": "Successful",
      "description": "Item has been processed successfully",
      "badgeColor": "green"
    },
    "productName": "R10 - R3500 FLASH Group Electricity",
    "productShortName": "FLASH Group",
    "quantity": 1,
    "price": 30.0000,
    "totalAmount": 30.0000,
    "transactionId": "bdf82429-9ab5-4f1a-bb9a-e469f4f05f05",
    "responseDate": "2025-10-21T12:57:51.831899",
    "productImage": "https://pagamio-assets.ams3.digitaloceanspaces.com/vas-uat/1756442263930-1756442259265_61l654.jpg",
    "brandName": "FLASH Group",
    "categoryName": "Electricity",
    "channelName": "Default",
    "merchantName": "Eudson Bambo",
    "partnerName": "Zapper",
    "aggregatorName": "FLASH"
  },
  ...
]

---

Transaction Status Codes

Code	Status	Description	Badge Color
0	COMPLETED	Item has been processed successfully	green
1	PENDING	Item is waiting to be processed	gray
2	PROCESSING	Item is currently being processed	blue
3	FAILED	Item processing has failed	red

Use the status.code field to filter or display transaction states programmatically.

---

Best Practices

1. Always include the Authorization Bearer token in your request.
2. Use exportAll=false for paginated queries to improve performance.
3. Use exportAll=true only when exporting data for reports.
4. Use filters (categoryName, brandName, aggregatorName, status, keyWord) to narrow down results.
5. Log transactionId for each transaction to help with reconciliation and troubleshooting.

---

Last updated: October 2025