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.

Payment History focuses on historical payments. It complements the Settlement APIs, which expose settlement batches and payment level settlement records.

Real-time versus historical data

• Webhooks and in-flight API responses provide real-time status for individual payments.

• Payment History reads from a replicated reporting store that is updated from payment and settlement events, usually within seconds. It is not intended for second by second monitoring.

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

If you need to understand how payments were grouped and funded in settlement batches, use the Settlement APIs together with Payment History.

Relationship to Settlement

Use Payment History when you need:

• Lists of payments for a partner, merchant, or terminal

• Filters based on payment fields such as status, tender type, and time range

• Aggregated views that focus on transactions rather than how they were settled

Use the Settlement APIs when you need:

• Merchant settlement batches that show how payments were grouped and funded

• Payment settlement records that show settlement amounts, currencies, and available times

• Status values that describe the settlement lifecycle for batches and payments

A common integration pattern is:

1. Use Payment History to identify the set of payments that matter for a report or investigation.

2. Use Settlement endpoints to retrieve settlement batches and payment settlement lines for those payments.

Choosing the right scope

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

Merchant scope is most frequently used for reconciliation and settlement reporting. Partner and terminal scopes are helpful for portfolio views and device level troubleshooting.

Pagination, sorting, and filters

• Always supply page and pageSize. The default size is fine for UI scroll views. Automated exports often use values around 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.

Exact parameter names and types are documented on the Pagination and Sorting page.

Consistency and delay

• The reporting database is eventually consistent. Most updates appear within a few seconds, but extremely large payment volumes or 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.

• If you run a job that must not miss records, prefer fixed time windows and page until you receive an empty data array.

Recommended call patterns

Use case	Pattern
Dashboard cards	Call once per minute with sortDirection=desc and pageSize=20.
End of day reconciliation	Use fixed fromDate and toDate for the business day. Iterate through pages until data is empty.
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	Use status=underpaid or status=overpaid combined with a one day date window.

When reconciliation also involves settlement data, you can use these patterns to pull the relevant payments, then call Settlement endpoints to retrieve batch and settlement line information.

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.

Other errors follow the general error handling guidance in the API.

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 minimize load on production systems.

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

• When working with settlement, use Payment History to identify the payments of interest, then use the Settlement APIs to retrieve merchant settlements and payment settlement records.

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