> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reporting/payment-history-concepts/pagination-and-sorting.md). # Pagination and Sorting `/Partners/{id}/payments`, `/Merchants/{id}/payments`, and `/Terminals/{id}/payments` all use the same pagination, sorting, and filter contract. Every call is a GET request with parameters supplied in the query string. No request body is required. **Query parameters** | Name | Type | Required | Default | Notes | | ----------------------------- | -------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- | | `from` | ISO 8601 | Yes | — | Inclusive start timestamp in UTC, e.g. `2025-09-01T00:00:00Z`. | | `to` | ISO 8601 | Yes | — | Exclusive end timestamp in UTC, e.g. `2025-09-02T00:00:00Z`. | | `page` | integer | Yes | `1` | One-based page number. | | `pageSize` | integer | Yes | `50` | Records per page. Maximum `500`. | | `sortBy` | string | No | `created` | Field to sort on. | | `sortDirection` | string | No | `desc` | `asc` or `desc`. | | `statusCode` | string | No | — | Filter by payment status. See [Payment Statuses](/payments/payment-statuses.md). | | `paymentSettlementStatusCode` | string | No | — | Filter by settlement status. See [Settlement Status Codes](/reference-guide/enumerations-and-schemas/settlement-status-codes.md). | | `trackingId` | string | No | — | Filter by tracking identifier. | | `pageId` | string | No | — | Opaque cursor for continuation, echoed from a prior response. | | `reference` | string | No | — | Filter by merchant reference, e.g. invoice number. | | `paymentCode` | string | No | — | Filter by payment code. | | `customerId` | string | No | — | Filter by customer ID. | | `descriptionSearch` | string | No | — | Case-sensitive text search over the description field. | | `reqCurrencyId` | integer | No | — | Filter by requested currency ID. | | `payCurrencyId` | integer | No | — | Filter by payment currency ID. | | `merchantId` | string | No | — | Filter to a single merchant. Partner scope only. | | `locationId` | string | No | — | Filter to a single location. Partner scope only. | **Payment status values** Valid values for `statusCode`: | Value | Description | | ------------------- | ---------------------------------------------------- | | `created` | Payment has been created. | | `processing` | Payment is being processed. | | `completed` | Payment completed successfully. | | `underpaid` | Payment received was less than the requested amount. | | `overpaid` | Payment received was more than the requested amount. | | `fullyRefunded` | Payment has been fully refunded. | | `partiallyRefunded` | Payment has been partially refunded. | | `expired` | Payment expired before completion. | | `invalid` | Payment is invalid. | | `cancelled` | Payment was cancelled. | **Settlement status values** Valid values for `paymentSettlementStatusCode`: | Value | Description | | ------------------ | --------------------------------------------------------- | | `created` | Payment settlement record has been created. | | `pending` | Payment settlement is pending processing. | | `processing` | Payment settlement is being processed. | | `completed` | Payment settlement has completed successfully. | | `error` | Payment settlement encountered an error. | | `initiationFailed` | Payment settlement initiation failed and requires review. | **Response structure** ```json { "data": [ ... ], "total": 27, "page": 1 } ``` | Field | Description | | ------- | ---------------------------------------------------------- | | `data` | Array of payment records for the current page. | | `total` | Total number of matching records at the time of the query. | | `page` | Current page number returned. | `pageSize` is supplied in the query but is not echoed in the response. Your client should track the value it requested. **Example request** ```bash curl -G "https://api.test.devs.beadpay.io/Merchants/mer_4e5a13aa/payments" \ -H "Authorization: Bearer $TOKEN" \ --data-urlencode "from=2025-09-01T00:00:00Z" \ --data-urlencode "to=2025-09-02T00:00:00Z" \ --data-urlencode "page=1" \ --data-urlencode "pageSize=50" \ --data-urlencode "sortBy=created" \ --data-urlencode "sortDirection=desc" \ --data-urlencode "statusCode=completed" ``` **Best practices** * Always supply `from`, `to`, `page`, and `pageSize` on every request. * Use `sortDirection=desc` on `created` to retrieve the most recent payments first. * Narrow `from` and `to` as much as possible — smaller windows reduce query cost and improve response time. * For paginated exports, advance through pages until `data` is an empty array. * For infinite scroll, advance the `from` window to the timestamp of the last record on the current page rather than incrementing `page` indefinitely. * Use `pageId` when resuming a previously read window to avoid duplicates. * Use `statusCode=underpaid` or `statusCode=overpaid` combined with a narrow date window for exception monitoring. * Treat `total` as a snapshot — new payments arriving after your query will change it on the next call. **Next steps** * Use [Partner Payments](/reporting/partner-payments.md) for portfolio-level history. * Use [Merchant Payments](/reporting/merchant-payments.md) for store-level history. * Use [Terminal Payments](/reporting/terminal-payments.md) for device-level history. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/reporting/payment-history-concepts/pagination-and-sorting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.