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.

Response schema differs at terminal scope

The three scopes accept the same query parameters, but they do not all return the same payload.

• /Merchants/{id}/payments and /Partners/{id}/payments return PagedDataResultOfPaymentResponse, holding PaymentResponse records.

• /Terminals/{id}/payments returns PagedDataResultOfPaymentInfo, holding PaymentInfo records.

Each envelope exposes data, total, and page, so the paging loop is the same at every scope. The record shape inside data is not.

PaymentInfo does not carry batchPeriod, locationId, locationName, merchantId, tenderType, transferType, originalSenderAddress, or the four refund lifecycle fields (refundLifecycleStatus, refundInitiatedAt, refundCompletedAt, refundFailureReason). It does carry fields that PaymentResponse omits, including trackingId, pageId, reqCurrencyId, payCurrencyId, emailReceipt, smsReceipt, cartItems, externalId, merchantLocation, transactions, paymentNotifications, webhookUrls, refundEmail, expiration, quoteExpiration, paymentAddress, and redirectUrl.

Filter support is not the same as field presence. TenderType is accepted as a filter on all three endpoints, but the tenderType value is not present on the records returned by terminal scope. If your report needs to read or group by tender type, query merchant or partner scope. Also note that customerId is an object on PaymentResponse and a string on PaymentInfo, and created is nullable on PaymentInfo.

Pagination, sorting, and filters

• Always supply Page and PageSize. Page is zero based and defaults to 0. PageSize defaults to 50 and has a maximum of 100. The default is fine for UI scroll views. For automated exports, stay within the maximum: use PageSize=100 and iterate pages rather than asking for a larger page.

• Sorting on the created timestamp in descending order is the fastest way to pull "latest payments". SortBy accepts only statusCode, expiration, quoteExpiration, created, and updated. SortDirection accepts asc or desc.

• Narrow From and To when possible. Both are date-time values. Smaller windows reduce query cost and speed up responses.

• Status filtering lets you retrieve only exceptions such as underpaid, overpaid, or invalid. The parameter is StatusCode, and it is an array: repeat it to pass more than one value, for example StatusCode=underpaid&StatusCode=overpaid.

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 From and To 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 From to the timestamp of the last item.
Exception monitoring	Use StatusCode=underpaid&StatusCode=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 a PageSize above the maximum of 100	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.

• Do not reuse one response parser across all three scopes. Terminal scope returns PaymentInfo, which is a different field set.

• 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.