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

# Transaction & Payout Statuses

Both APIs represent the lifecycle of a transaction with a `status` field. Knowing these values up front is essential for building reliable polling logic and webhook handlers.

## Payments API Statuses

Used for transactions created via `Generate Transaction` and retrieved via `Get Transactions`:

| Status      | Meaning                                                                  |
| ----------- | ------------------------------------------------------------------------ |
| `completed` | The payment was successfully received.                                   |
| `pending`   | The payment is still awaiting completion.                                |
| `cancelled` | The transaction was canceled by the payment gateway, failed, or expired. |

A transaction is only marked `cancelled` for one of three reasons: the payment gateway canceled it, it failed outright, or it expired before the customer completed payment.

The Disbursement API's **Wallet** endpoints (`Get Wallets` filter, `Get Wallet Transactions` filter) also reference this same three-value set (`completed`, `pending`, `cancelled`) when filtering wallet-level activity.

## Disbursement API Statuses

Used for payouts created via `Process Disbursement` and retrieved via `Get Transactions` (Disbursement):

| Status      | Meaning                                                                           |
| ----------- | --------------------------------------------------------------------------------- |
| `pending`   | The payout has been submitted and is processing.                                  |
| `cancelled` | The payout was either failed or cancelled. No funds were transferred.             |
| `completed` | The payout was successfully processed and confirmed. Funds have been transferred. |

The Disbursement API uses the **same three status values as the Payments API** (`pending`, `cancelled`, `completed`) — there is no separate `failed` or `success` value. See [Webhooks & Redirects](/webhooks-and-redirects) for how these appear in webhook payloads.

## Why This Matters

* **`Generate Transaction`** and **`Process Disbursement`** both return a `pending` status immediately upon submission — neither call is synchronous with the actual payment/payout completing. You must check the final status afterward.
* The two ways to learn the final status, in order of preference:
  1. **Listen for a webhook** on the `callback_webhook_url` you supplied, which fires once the final status is known (see [Webhooks & Redirects](/webhooks-and-redirects)). This should be your primary mechanism.
  2. **Look up the single transaction** via `Get Transactions` filtered by your `reference_no`, as a fallback — not for routine polling or listing (see [Looking Up Transactions](/looking-up-transactions)).
* For the Payments API, a successful payment also triggers a browser redirect to `success_redirect_url` (or `failure_redirect_url` on failure/cancellation).

## Looking Up a Transaction's Status

Listing/pagination via `Get Transactions` is discouraged and being phased out — see [Looking Up Transactions](/looking-up-transactions) for details. Avoid unfiltered or broad-range polling, especially as your transaction volume grows; it's expensive to serve and is exactly the pattern the platform is moving away from.

The recommended approach is:

1. **Rely on webhooks first** — your `callback_webhook_url` fires once the final status is known, so you shouldn't need to poll for routine tracking (see [Webhooks & Redirects](/webhooks-and-redirects)).
2. **When you do need to check a status directly, filter by `reference_no` only** — look up the one transaction you care about rather than listing/paging through many:

```text
GET /v1/biller/transactions?reference_no=YOUR_REFERENCE_NO
GET /v1/api/disbursement/transactions?reference_no=YOUR_REFERENCE_NO
```

A dedicated single-transaction inquiry endpoint keyed only on `reference_no` is planned to replace `Get Transactions` for this use case — see [Looking Up Transactions](/looking-up-transactions) for the full migration guidance.