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.
paymentSettlementStatusCode	string	No	—	Filter by settlement status. See Settlement Status Codes.
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

{
  "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

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 for portfolio-level history.

• Use Merchant Payments for store-level history.

• Use Terminal Payments for device-level history.