> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.epaygames.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.epaygames.io/_mcp/server.

# Looking Up Transactions

Listing/pagination via `Get Transactions` is **discouraged** and being phased out. Unfiltered or broadly-filtered list calls are expensive to serve, especially as your transaction volume grows. Design your integration around looking up **one transaction at a time by `reference_no`** instead.

## Why We're Moving Away From Listing

`Get Transactions` (on both the Payments API and the Disbursement API) currently supports pagination (`page`, `per_page`) and several filters (`status`, `date`/`date_from`/`date_to`, `channel`, etc.). In practice, broad or unfiltered calls to this endpoint are resource-intensive to serve — the cost scales with how many transactions you (and the platform as a whole) have accumulated over time, not with how many results you actually need.

Because of this, `Get Transactions` as a general-purpose listing/browsing endpoint is being deprecated. A lighter-weight, single-transaction inquiry endpoint keyed only on `reference_no` is planned to replace it as the primary way to check a transaction's status.

That dedicated single-transaction endpoint isn't in this collection yet — this page will be updated with its request/response details once it ships. Until then, the guidance below is how to get the same result using what's currently available.

## Recommended Approach Today

* **Always look up by `reference_no`.** Since you choose this value when you create a transaction or disbursement (see [Request & Response Format](/request-response-format)), you already have it on hand — use it as the single filter on `Get Transactions` rather than paging through unfiltered results.
* **Prefer webhooks over polling entirely.** The most efficient pattern is to not call `Get Transactions` at all for routine status tracking — rely on your `callback_webhook_url` (see [Webhooks & Redirects](/webhooks-and-redirects)) and treat `Get Transactions` as a fallback for the rare cases where a webhook wasn't received.
* **Avoid unfiltered or date-range listing**, especially recurring/scheduled jobs that page through "all transactions" or "all transactions this month." This is exactly the usage pattern that's expensive at scale and the reason the endpoint is being deprecated.
* **Don't build dashboards or reporting features on top of `Get Transactions` pagination.** If you need bulk reporting, treat that as a separate conversation with Epaygames rather than something to build on this endpoint.

## What This Means for Pagination Parameters

The `page` and `per_page` parameters (max `per_page`: 100) still exist on `Get Transactions` today, but they should be treated as **legacy** rather than a recommended integration pattern:

| Parameter                                | Status                                                                                           |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `reference_no`                           | ✅ Recommended — the primary way to look up a transaction going forward.                          |
| `provider_reference_no` / `channel`      | Fine as a secondary filter alongside `reference_no` when you have it.                            |
| `status`, `date`, `date_from`, `date_to` | ⚠️ Use sparingly — avoid combining these with unbounded pagination for routine polling.          |
| `page`, `per_page`                       | ⚠️ Legacy — works today, but don't build new integration logic around browsing pages of results. |

## Migration Checklist

#### Store reference\_no as your primary key

Make sure every transaction/disbursement you create is tracked in your own system by the `reference_no` you assigned it.

#### Switch routine status checks to webhooks

If you're currently polling `Get Transactions` on a schedule, replace that with a `callback_webhook_url` handler.

#### Replace any bulk/list usage with per-reference\_no lookups

Anywhere you currently fetch a page of transactions and filter client-side, call `Get Transactions` filtered by a single `reference_no` instead.

#### Watch for the dedicated inquiry endpoint

When the single-transaction inquiry endpoint (keyed on `reference_no`) ships, plan to migrate to it — it will be the intended long-term replacement for this use case.