> 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 accept the same query parameters: the same pagination, sorting, and filter contract applies to all three. They do **not** all return the same response schema. See the Response schema by scope section below before you write a shared parser. 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` | date-time | Yes | — | Start of the payment creation-time window, in UTC. Accepts either a full ISO 8601 timestamp (`2025-09-01T00:00:00Z`) or a date-only value (`2025-09-01`). | | `To` | date-time | Yes | — | End of the payment creation-time window, in UTC. Accepts either a full ISO 8601 timestamp or a date-only value, same as `From`. | | `Page` | integer | Yes | `0` | Zero-based page number. The first page is `0`, not `1`. | | `PageSize` | integer | Yes | `50` | Records per page. Maximum `100`. | | `SortBy` | string | No | `created` | Field to sort on. Allowed values: `statusCode`, `expiration`, `quoteExpiration`, `created`, `updated`. | | `SortDirection` | string | No | `desc` | `asc` or `desc`. | | `StatusCode` | array of strings | No | — | Filter by payment status. Repeat the parameter for multiple values. See [Payment Statuses](/payments/payment-statuses.md). | | `TenderType` | array of strings | No | — | Filter by tender type. Repeat the parameter for multiple values. See [Tender Types](/reference-guide/enumerations-and-schemas/tender-types.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. Exact, case-sensitive match. | | `PaymentCode` | string | No | — | Filter by payment code. Case-insensitive substring match. | | `CustomerId` | string | No | — | Filter by customer ID. Exact match. | | `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. | | `LocationName` | string | No | — | Filter by location name. Case-insensitive substring match. Partner and Merchant scope only, see below. | | `TerminalName` | string | No | — | Filter by terminal name. Case-insensitive substring match. Partner and Merchant scope only, see below. | > **Parameter casing:** all query parameters on these endpoints are capitalized (`From`, `To`, `Page`, `PageSize`, `StatusCode`, and so on). Lowercase parameter names have not been verified as accepted, use the capitalized form shown above. > **Every parameter above is accepted on all three endpoints, but two of them only filter on two of the three.** `LocationName` and `TerminalName` filter as expected on [Partner Payments](/reporting/partner-payments.md) and [Merchant Payments](/reporting/merchant-payments.md). On [Terminal Payments](/reporting/terminal-payments.md) both are accepted, return HTTP 200, and have no effect on the result set: a value matching nothing returns the same records as an unfiltered request. Confirmed by direct testing. Do not rely on either parameter at terminal scope. > **`To` appears to be exclusive at the boundary.** On the Settlement endpoints, a same-day window (`From` and `To` set to the same date) returns zero records, while extending `To` by one day returns the expected record. Treat `To` as exclusive and extend it past the last day you want included. This has not been characterized on the payment endpoints. > **Note:** `merchantId` and `locationId` as exact-match filters are not available. Neither is `settlementId` or `batchId`. Use `LocationName` and `TerminalName` for name-based filtering, or filter results client-side. To go from a settlement to its payments, see [Settlement Reconciliation Patterns](/settlement/settlement-reconciliation-patterns.md). > **Some filters have no matching response field at merchant and partner scope.** `TrackingId`, `PageId`, `ReqCurrencyId`, and `PayCurrencyId` are accepted as filters everywhere, but their values are only returned on records from `/Terminals/{id}/payments`. Filter on them if you already hold the value, do not expect to read them back at merchant or partner scope. **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` | Reserved. Will indicate the payment has been fully refunded. | | `partiallyRefunded` | Reserved. Will indicate the payment has been partially refunded. | | `expired` | Payment expired before completion. | | `invalid` | Payment is invalid. | | `cancelled` | Payment was cancelled. | See [Payment Statuses](/payments/payment-statuses.md) for full status handling guidance, including which statuses are stateful versus final. **Response schema by scope** The parameter contract is shared. The response object is not. | Scope | Response object | Notable difference | | ------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Partner Payments](/reporting/partner-payments.md) `/Partners/{id}/payments` | `PaymentResponse` | Full merchant and location context, tender and transfer type, refund lifecycle fields | | [Merchant Payments](/reporting/merchant-payments.md) `/Merchants/{id}/payments` | `PaymentResponse` | Same as Partner scope | | [Terminal Payments](/reporting/terminal-payments.md) `/Terminals/{id}/payments` | `PaymentInfo` | Device oriented fields instead: `trackingId`, `pageId`, `reqCurrencyId`, `payCurrencyId`, `emailReceipt`, `smsReceipt`, `cartItems`, `externalId`, `merchantLocation`, `transactions`, `paymentNotifications`, `webhookUrls`, `refundEmail`, `expiration`, `quoteExpiration`, `paymentAddress`, `redirectUrl` | Terminal scope does **not** return `batchPeriod`, `locationId`, `locationName`, `merchantId`, `tenderType`, `transferType`, `originalSenderAddress`, or any of the four refund lifecycle fields. Two further differences to watch: * `customerId` is an object at merchant and partner scope, and a string at terminal scope. * `created` and `updated` are always present at merchant and partner scope. At terminal scope both are declared nullable, so handle null defensively even though they were populated in testing. Do not write one response parser and reuse it across all three scopes. **Settlement status on payment history** Payment history responses do not include a `paymentSettlementStatusCode` field, and it is not available as a filter on these endpoints. For settlement lifecycle status, each payment carries settlement linkage fields: | Field | Partner | Merchant | Terminal | | -------------- | ------- | -------- | -------- | | `settlementId` | Yes | Yes | Yes | | `batchId` | Yes | Yes | Yes | | `batchStatus` | Yes | Yes | Yes | | `batchPeriod` | Yes | Yes | No | All of these are null until the payment is batched. `batchStatus` carries `open`, `closed`, or `hold`, which is a batch state, not a settlement state. Settlement state itself lives on the settlement record. See [Payment Settlement Detail](/settlement/payment-settlement-detail.md) for the full pattern, [Settlement Reconciliation Patterns](/settlement/settlement-reconciliation-patterns.md) for portfolio scale reconciliation, and [Settlement Status Codes](/reference-guide/enumerations-and-schemas/settlement-status-codes.md) for the status enums that apply to settlement-side objects. **Response structure** ```json { "data": [ ... ], "total": 27, "page": 0 } ``` | 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 (zero-based). | The envelope is the same on all three endpoints, only the objects inside `data` differ. `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 "X-Api-Key: {apiKey}" \ --data-urlencode "From=2025-09-01T00:00:00Z" \ --data-urlencode "To=2025-09-02T00:00:00Z" \ --data-urlencode "Page=0" \ --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 `SortBy=created` with `SortDirection=desc` to retrieve the most recent payments first. * Narrow `From` and `To` as much as possible, smaller windows reduce query cost and improve response time. * Keep `PageSize` at or below the maximum of `100`. A larger value is rejected. * 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&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. * Use `LocationName` or `TerminalName` to narrow a query to a specific store or device before falling back to client-side filtering. * Use the `updated` timestamp to detect payment changes, but not to detect settlement events. Assigning a settlement to a payment does not change the payment record. **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.