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	None	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	None	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	None	Filter by payment status. Repeat the parameter for multiple values. See Payment Statuses.
TenderType	array of strings	No	None	Filter by tender type. Repeat the parameter for multiple values. See Tender Types.
TrackingId	string	No	None	Filter by tracking identifier.
PageId	string	No	None	Opaque cursor for continuation, echoed from a prior response.
Reference	string	No	None	Filter by merchant reference, e.g. invoice number. Exact, case-sensitive match.
PaymentCode	string	No	None	Filter by payment code. Case-insensitive substring match.
CustomerId	string	No	None	Filter by customer ID. Exact match.
DescriptionSearch	string	No	None	Case-sensitive text search over the description field.
ReqCurrencyId	integer	No	None	Filter by requested currency ID.
PayCurrencyId	integer	No	None	Filter by payment currency ID.
LocationName	string	No	None	Filter by location name. Case-insensitive substring match. Partner and Merchant scope only, see below.
TerminalName	string	No	None	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 and Merchant Payments. On Terminal Payments 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.

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	Paid. The customer sent the requested amount. Final status.
overpaid	Paid. The customer sent more than the requested amount. The requested amount settles and the excess is returned to the payer. Final status.
underpaid	Not paid. The customer sent less than the requested amount. Final status.
expired	Payment expired before completion. Final status.
abandoned	Payment was created but never started, and was closed by Bead. Final status.
invalid	Payment is invalid. Final status.
cancelled	Payment was cancelled. Final status.
partiallyRefunded	Reserved. Accepted as a filter value. See Payment Statuses.
fullyRefunded	Reserved. Accepted as a filter value. See Payment Statuses.

A reclaim does not change statusCode. Read refundLifecycleStatus on the returned records to see reclaim progress. See Payment Statuses for full status handling guidance.

Response schema by scope

The parameter contract is shared. The response object is not.

Scope	Response object	Notable difference
Partner Payments /Partners/{id}/payments	PaymentResponse	Full merchant and location context, tender and transfer type, refund lifecycle fields
Merchant Payments /Merchants/{id}/payments	PaymentResponse	Same as Partner scope
Terminal Payments /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. completed and overpaid payments are 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 for the full pattern, Settlement Reconciliation Patterns for portfolio scale reconciliation, and Settlement Status Codes for the status enums that apply to settlement-side objects.

Response structure

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

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.

• For paid payments, filter with StatusCode=completed&StatusCode=overpaid.

• Use StatusCode=overpaid&StatusCode=underpaid combined with a narrow date window, then read refundLifecycleStatus, to monitor reclaims.

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

• Use Merchant Payments for store-level history.

• Use Terminal Payments for device-level history.