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

# Payouts

> Send money to a phone, bank account, or crypto address.

A payout sends money out of your project to a recipient. Payment intents bring money in.
Payouts are a separate resource with their own endpoint set and lifecycle.

Amounts work exactly as they do on a payment: `amount` is in major units, so `50` means
50.00. See [API conventions](/api-conventions#amounts).

## Lifecycle

| Status       | Meaning                                                   |
| ------------ | --------------------------------------------------------- |
| `pending`    | Received and queued; not yet dispatched to the provider.  |
| `processing` | Sent to the provider; awaiting confirmation.              |
| `completed`  | The provider confirmed successful delivery.               |
| `failed`     | The provider rejected or could not complete the transfer. |

There is no automatic retry. **A failed payout is final.** Create a new payout if you need
to retry. There is no `cancelled` or `reversed` status.

## Verifying a payout

Webhooks are the primary signal. Orchestrate delivers `payout.initiated`, `payout.completed` and `payout.failed` to
your project's configured endpoints. See [Webhooks](/webhooks) for payload details and
signing.

To read the current state of a payout at any time:

```bash theme={null}
curl https://api.orqex.com/v1/payouts/po_... \
  -H "Authorization: Bearer sk_live_..."
```

To force Orchestrate to re-check the payout status with the provider before returning:

```bash theme={null}
curl https://api.orqex.com/v1/payouts/po_.../sync \
  -H "Authorization: Bearer sk_live_..."
```

The sync endpoint contacts the provider, updates the payout if the status has changed, and
returns the refreshed payout in `data`.

### Raw provider record

For support and debugging, fetch the verbatim record the provider returned:

```bash theme={null}
curl https://api.orqex.com/v1/payouts/po_.../inspect \
  -H "Authorization: Bearer sk_live_..."
```

The `data` object contains:

| Field                    | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `gateway`                | Identifier of the gateway that handled this payout.    |
| `gateway_transaction_id` | The provider's transaction reference.                  |
| `retrieved_at`           | When Orchestrate fetched the record from the provider. |
| `payload`                | The verbatim response object from the provider.        |

This endpoint is not intended for business logic — it is a diagnostic tool.

## Listing payouts

```bash theme={null}
curl "https://api.orqex.com/v1/payouts?status=completed&per_page=20" \
  -H "Authorization: Bearer sk_live_..."
```

Available query parameters:

| Parameter         | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| `status`          | Filter by status: `pending`, `processing`, `completed`, or `failed`. |
| `method`          | Filter by method code.                                               |
| `currency`        | Filter by ISO 4217 currency code.                                    |
| `customer_id`     | Filter by customer identifier.                                       |
| `created_at[gte]` | Created on or after this date.                                       |
| `created_at[lte]` | Created on or before this date.                                      |
| `per_page`        | Number of results per page.                                          |

Responses use cursor-based pagination. See [API conventions](/api-conventions) for how to
navigate `next_cursor` and `prev_cursor`.

## Available payout methods

Which methods you can pay out to depends on your project's gateway configuration. Check
your dashboard to see the method codes available and the instrument type each method
requires.