Pagination and Sorting

Purpose

All three payment-history endpoints—/Partners/{id}/payments, /Merchants/{id}/payments, and /Terminals/{id}/payments—share the same paging and filtering contract. Each call is a POST request with pagination, sorting, and filter values supplied as query-string parameters. No request body is required.

Query parameters

Parameter	Type	Required	Default / limits	Description & examples
page	integer	no	0	0-based page index. page=2&pageSize=50 returns the third block of 50 records.
pageSize	integer	no	50 • max 200*	Number of rows per page.
sortBy	string	no	created	Field to sort on (created, amount, statusCode, …).
sortDirection	string	no	desc	asc or desc.
fromDate	ISO-8601 string	no	–	Payments created ≥ this timestamp. 2025-04-01T00:00:00Z
toDate	ISO-8601 string	no	–	Payments created ≤ this timestamp.
status	string	no	–	One of: created, processing, completed, underpaid, overpaid, fullyRefunded, partiallyRefunded, expired, invalid, cancelled

* Adjust the maximum if your implementation differs.

Request example

POST /Terminals/abc123/payments
?page=0&pageSize=50
&sortBy=created&sortDirection=desc
&fromDate=2025-04-01T00:00:00Z
&toDate=2025-04-24T23:59:59Z

Curl

curl -X POST \
  "https://api.test.devs.beadpay.io/Terminals/abc123/payments?page=0&pageSize=50&sortBy=created&sortDirection=desc&fromDate=2025-04-01T00:00:00Z&toDate=2025-04-24T23:59:59Z"

(No JSON body—everything is passed in the query string.)

Response example (trimmed)

{
  "data": [
    {
      "id": "pay_5d3a9e",
      "created": "2025-04-18T14:22:31Z",
      "updated": "2025-04-18T14:22:31Z",
      "terminalId": "stringstringstringstring",
      "statusCode": "completed",
      "amounts": { ... }
    }
  ],
  "total": 27,
  "page": 0
}

Field	Description
data	Array of payment objects for this page.
total	Total number of payments that match the filters.
page	Page index you requested.

pageSize is supplied in the query but is not echoed in the response; your client should keep track of the size it requested.

Best practices

1. Always include page and pageSize to keep response times predictable.

2. For infinite scroll, advance the fromDate window instead of incrementing page after you reach the last page.

3. Cache total sparingly—refresh only when you need an updated count.