Payment History Concepts

Purpose

This page explains how the Payment History endpoints work, when to use each scope (partner, merchant, terminal), and how to design efficient queries that scale with volume.

Real-time versus historical data

• Webhooks and the in-flight API responses provide real-time status.

• Payment History reads from a replicated reporting store that is updated within seconds of settlement events but is not intended for second-by-second monitoring.

• Use the endpoints for reconciliation, dashboards, and audits rather than operational alerting.

Choosing the right scope

Scope	Best when you need…	Endpoint
Partner	Portfolio-level dashboards, KPIs, partner statements	/Partners/{id}/payments
Merchant	Store-level sales, settlement files, or per-location reports	/Merchants/{id}/payments
Terminal	Device troubleshooting, in-store last-payments view	/Terminals/{id}/payments

Pagination, sorting, and filters

• Always supply page and pageSize; the default size is fine for UI scroll views, but automated exports often use 200.

• Sorting on the created timestamp in descending order is the fastest way to pull “latest payments”.

• Narrow fromDate and toDate when possible. Smaller windows reduce query cost and speed up responses.

• Status filtering lets you retrieve only exceptions such as underpaid, overpaid, or invalid.

Consistency and delay

• The reporting database is eventually consistent. Most updates appear within a few seconds, but extremely large settlement batches can take a minute or two.

• Treat the returned total count as a snapshot. New payments that arrive after your query will increase the total on the next call.

Recommended call patterns

Use-case	Pattern
Dashboard cards	Call once per minute with sortDirection=desc and pageSize=20.
End-of-day reconciliation	Fixed fromDate and toDate covering the business day; iterate through pages until the response contains an empty data array.
Infinite scroll UI	Keep sortDirection=desc, move page forward until you reach the last page, then extend fromDate to the timestamp of the last item.
Exception monitoring	status=underpaid or status=overpaid combined with a one-day date window.

Error handling

HTTP status	Typical cause	Recovery
400	Invalid date range or page size too large	Correct the query parameters.
404	Scope identifier not found	Verify the partner, merchant, or terminal id.
429	Too many requests	Back off and retry with exponential delay.

Best practices

• Cache the first page in memory for a short period if multiple components read it in quick succession.

• Perform nightly exports in off-hours to minimise load on production systems.

• Use partner-level history for bulk analytics, then drill down with merchant or terminal scope only when investigating anomalies.

Refer to the Pagination and Sorting page for exact parameter definitions, then jump to the endpoint reference that matches your scope.