# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.bead.xyz/reporting/payment-history-concepts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.