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

# Payout lifecycle

> Every state a payout moves through, what triggers each transition, and the time limits that seal an unresolved payout.

A payout's status derives from what the provider reported and how long the payout has been waiting. There are four states and no automatic retry: a payout either delivers or fails, and a failed payout is final — create a new one to retry.

## States

```mermaid theme={null}
stateDiagram-v2
    direction LR
    [*] --> pending : payout created
    pending --> processing : dispatched to the provider
    pending --> failed : never dispatched\nwithin 72 hours
    processing --> completed : provider confirmed delivery
    processing --> failed : provider rejected,\nor no resolution within 48 hours
    completed --> [*]
    failed --> [*]
```

| State        | Meaning                                                                                      |
| ------------ | -------------------------------------------------------------------------------------------- |
| `pending`    | Received and queued; not yet dispatched to a provider. No funds have moved.                  |
| `processing` | Sent to the provider; awaiting its confirmation. `initiated_at` marks this moment.           |
| `completed`  | The provider confirmed successful delivery. Terminal.                                        |
| `failed`     | The provider rejected the transfer, or the payout was sealed after its time limit. Terminal. |

## Time limits

| Situation                                      | Default limit                | Outcome                                                                                                                                                      |
| ---------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Stuck in `pending`, never dispatched           | 72 hours                     | Sealed `failed` with the `PAYOUT_TIMEOUT` failure code. Safe by construction: no funds moved.                                                                |
| Stuck in `processing`, provider never resolves | 48 hours from `initiated_at` | Re-verified with the provider one last time, then sealed `failed` with `PAYOUT_TIMEOUT`. A confirmation landing inside the window always wins over the seal. |

While a payout is `processing`, Orchestrate keeps re-verifying it against the provider on its own — webhooks are the primary signal, polling is the backstop. You never need to poll yourself; listen for `payout.completed` / `payout.failed` and treat `GET /payouts/{id}` as the on-demand read.

<Note>
  A payout sealed with `PAYOUT_TIMEOUT` was never confirmed either way by the provider. If the provider settles it after the seal, contact support — funds are reconciled before any retry, so never blindly re-create a sealed payout without checking its final state provider-side.
</Note>

## Timestamps you can rely on

| Field          | Meaning                                             |
| -------------- | --------------------------------------------------- |
| `initiated_at` | When the payout was first dispatched to a provider. |
| `completed_at` | When delivery was confirmed.                        |
| `failed_at`    | When the payout failed or was sealed.               |