> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/payments/transaction-retrieval.md).

# Retrieving transactions

Resolve an outcome you did not receive, and avoid double-charging.

The API provides transaction retrieval capabilities that allow you to query and check the status of transactions when processing errors occur. This is essential for handling scenarios where:

* API responses are not received due to network timeouts
* Webhooks fail to deliver
* A transaction returns an `Interrupted` status, indicating an unknown final state

When you call the `GET /transactions` (List Transactions) endpoint, the API returns a paginated list of transactions for your account, such as sales, authorizations, token operations, and so on. The endpoint supports comprehensive filtering and sorting options to help you locate specific transactions or identify processing issues. When you already hold a transaction ID, `GET /transactions/{id}` returns that one transaction directly.

{% hint style="danger" %}
This is how you prevent duplicate charges. When a request times out or returns `Interrupted`, the transaction may already have succeeded. Look it up before retrying.
{% endhint %}

## Resolving an uncertain outcome

The reliable way to find a transaction you are not sure about is by the `referenceId` you sent on the original request - which is why it is worth always sending one.

{% stepper %}
{% step %}

## Send a referenceId on every request

Choose a value your system can reproduce, so you can look the transaction up later without having captured the response.
{% endstep %}

{% step %}

## Query by that reference

```http
GET /transactions?filters=referenceId==ref_238832ae
```

{% endstep %}

{% step %}

## Branch on what you find

An empty list does not prove that the request failed: a transaction request can still be in flight before a transaction record is available. Wait, query again, and check configured webhooks. If the outcome remains unknown, contact support before submitting another charge.

When you find a transaction, inspect `status`, `resultCode`, and `transactionResponses[].responseCode`. `Completed` includes both approvals and declines; earlier states can still be in progress.
{% endstep %}
{% endstepper %}

## Getting one transaction

When you already have the transaction ID, fetch it directly instead of filtering the list:

```http
GET /transactions/trx_01JWBPE27KHY2K4J7A13ATQ786
```

The response is the same transaction object the list returns. An unknown ID, or a transaction that belongs to another merchant, returns `404`.

## Checking what can still be refunded

Sales and captures report a `refundableAmount`: the amount, in the smallest denomination of the currency, that can still be refunded against them. Read it before you offer a refund, so you never request more than the balance.

* It normally becomes available within seconds of approval.
* It is `0` once the transaction is fully refunded or voided.
* It is absent on authorizations, refunds, voids, and declined transactions. It can also be absent briefly after a sale or capture is approved. Absence does not mean unlimited: it means the value is not available yet, or does not apply.

A refund response carries its own `refundableAmount`: the balance that remains on the original transaction after that refund. When the gateway declines the refund, it equals the balance before the attempt.

## Filtering and sorting

Available fields for both `filters` and `sorts`: `id`, `timestamp`, `referenceId`, `orderNumber`, `invoiceNumber`, `type`, `amount`, `status`.

```http
GET /transactions?filters=timestamp>=2025-05-21T01:00:00,type==Sale|Capture&sorts=-timestamp,type
```

Use `|` for OR conditions within a field, and a `-` prefix on a sort field for descending order. See [Request conventions](/get-started/conventions.md#filtering-sorting-and-paging) for the full syntax, including paging.

## Also useful for

* **Tracking an** [**ACH**](/payments/ach.md) **transfer** through `Processing` and `AwaitingSettlement` to completion, without waiting for the webhook.
* **Reconciling a settlement line** back to its transaction - a settled transaction reports a `transactionId`, which you can look up with `?filters=id==trx_...`. See [Settlements](/settlement-reporting/settlements.md).