> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eqxpay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts

> The quote-and-commit flow for stablecoin-to-fiat payouts to beneficiaries

A **payout** is EQX's primary integrator→beneficiary flow. It converts a stablecoin amount into local fiat delivered to a beneficiary's mobile money wallet or bank account.

## Flow overview

```
1. GET  /v1/api/routes                   → choose corridor
2. POST /v1/api/quotes                   → lock rate (90s TTL)
3. POST /v1/api/transactions/commit      → execute payout
4. GET  /v1/api/transactions/:id         → poll status (or use webhooks)
```

## Quotes

A quote locks a conversion rate for a specific corridor and amount. Quotes expire after **90 seconds**. You must commit the quote before it expires.

Key quote fields:

| Field                | Description                              |
| -------------------- | ---------------------------------------- |
| `quote_id`           | Reference for the commit step            |
| `source_amount`      | Amount of stablecoin to be consumed      |
| `destination_amount` | Fiat amount the beneficiary will receive |
| `rate`               | Locked exchange rate                     |
| `expires_at`         | Quote expiry timestamp (ISO 8601)        |

## Payout transactions

Committing a quote creates a **payout transaction**. The transaction moves through these statuses:

```
PROCESSING → DISPATCHED → COMPLETED
           ↘ FAILED
           ↘ RECONCILIATION_REQUIRED
```

| Status                    | Meaning                                              |
| ------------------------- | ---------------------------------------------------- |
| `PROCESSING`              | Committed, awaiting dispatch to provider             |
| `DISPATCHED`              | Submitted to payout provider                         |
| `COMPLETED`               | Provider confirmed delivery to beneficiary           |
| `FAILED`                  | Terminal failure                                     |
| `RECONCILIATION_REQUIRED` | Provider response is ambiguous; manual review needed |

## Reliability expectations

EQX is designed, monitored, and operated to get as close to a **100% successful payout rate** as possible. We validate requests before dispatch, reserve liquidity before execution, use idempotency for safe retries, and reconcile ambiguous provider responses instead of silently dropping them.

Some payout outcomes still depend on external bank, mobile money, switch, and provider systems. A transaction can be delayed, rejected, reversed, or marked for reconciliation because of beneficiary account issues, network downtime, provider limits, compliance checks, or responses returned by the receiving institution.

Always use the transaction status endpoint and webhooks as the source of truth for final payout state. Treat `COMPLETED` as successful delivery, `FAILED` as terminal failure, and `RECONCILIATION_REQUIRED` as an operational review state until EQX confirms the final outcome.

## Pagination

`GET /v1/api/transactions` supports offset pagination via `page` and `per_page` query parameters. Default page size is 20; maximum is 100.