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

# Payout Approvals

> How payouts that need your team's approval move through their lifecycle, and how your integration tracks them.

Your team can set **approval policies** so that some bank and crypto payouts, including the ones created through the API, wait for one or more approval steps before Ralio sends them. Payouts that no policy matches are sent as usual.

> [!WARNING]
>
> **Approvals are always made by people, never by the API.** A member of your team approves or rejects each step from the Ralio dashboard with two-factor authentication. Your integration only follows the result, through [webhooks](#webhooks) or the [`approval` block](#the-approval-block).

## Lifecycle

A payout that matches a policy stops in `PENDING_APPROVAL` (after the OTP, when one is required), with its funds reserved:

```text theme={null}
CREATED ─► PENDING_APPROVAL ─► PENDING ─► SETTLED
                  │               └─► FAILED
                  ├─► REJECTED
                  ├─► EXPIRED
                  └─► CANCELED
```

| `state` | Meaning |
| :- | :- |
| `PENDING_APPROVAL` | Waiting for every approval step. |
| `REJECTED` | An approver rejected it. Final: never sent, funds released. |
| `EXPIRED` | `approval.expiresAt` passed first. Final: never sent, funds released. |
| `CANCELED` | Your team canceled it while waiting. Final: funds released. |

Once approved, it continues as a regular payout. If you fixed the amount the recipient receives, it is requoted on approval, so the final amounts can differ from the ones at creation.

## The `approval` block

The create, validate OTP and order details responses (bank and crypto) include `approval`. It is `null` when the payout doesn't need approval, and the order lists don't include it.

| Field | Description |
| :- | :- |
| `expiresAt` | Deadline to complete every step. |
| `progress.approvedSteps` | Steps approved so far. |
| `progress.steps` | Total steps the payout needs. |
| `steps[]` | Each step's `number`, `approved` and `approvedAt` (`null` until approved). |
| `rejection` | `null`, or the `reason` and `rejectedAt` when it was rejected. |

To list the payouts that are waiting, filter the [order lists](https://doc.raliopay.com/api-reference/orders/list-merchant-orders.md) with `state_eq=PENDING_APPROVAL`.

## Webhooks

| Event | When |
| :- | :- |
| [`payout_approval_required`](https://doc.raliopay.com/webhooks-events/payout/payout-approval-required) | The payout enters `PENDING_APPROVAL` |
| [`payout_approved`](https://doc.raliopay.com/webhooks-events/payout/payout-approved) | The last step is approved |
| [`payout_rejected`](https://doc.raliopay.com/webhooks-events/payout/payout-rejected) | An approver rejects it |
| [`payout_expired`](https://doc.raliopay.com/webhooks-events/payout/payout-expired) | The deadline passes |
| [`payout_canceled`](https://doc.raliopay.com/webhooks-events/payout/payout-canceled) | Your team cancels it while it is waiting |

Intermediate approvals don't send a webhook.

> [!WARNING]
>
> `state` and `data.status` can return values your integration hasn't seen before. Don't treat an unknown value as an error: keep the payout open and wait for the next event.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.