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

# Overview

> The unit of money movement in Cleff. A Payout is created in pending_approval, validated by a Decision, and disbursed once approved.

A **Payout** represents a single instruction to move funds from a Business's
Cleff account to a Beneficiary. Every Payout belongs to exactly one Business
and one `environment` (`sandbox` or `production`) and is identified by a
server-issued `payout_id`.

## Lifecycle

A Payout flows through an explicit state machine:

| State              | Meaning                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `pending_approval` | Created; awaiting a Decision from a Validator (human or automated).                                                   |
| `approved`         | A Decision approved the Payout; the disbursement is dispatching or in flight.                                         |
| `rejected`         | A Decision rejected the Payout. Terminal.                                                                             |
| `disbursed`        | The provider confirmed the funds left. Provisional; a rail return can still move it to `returned`.                    |
| `settled`          | The return window closed without a return; the funds are final. A late rail return can still move it to `returned`.   |
| `returned`         | The rail returned the funds after disbursement. Terminal.                                                             |
| `failed`           | The disbursement attempt failed. Terminal; recover by authoring a replacement Payout linked via `replaces_payout_id`. |
| `canceled`         | Canceled before the funds were sent. Terminal.                                                                        |
| `compliance_hold`  | Paused for provider AML/sanctions review; returns to its previous state when cleared.                                 |

See ADR-0010 for the state-machine and disbursement-attempt model. The
Payout response surfaces only the convenience triple from the latest
DisbursementAttempt; the attempts list itself is intentionally not exposed.

## Idempotency

`POST /v1/payouts` is idempotent on `(Business, environment, idempotency_key)`
within a 24-hour window. A replay returns the original Payout with HTTP 200
instead of 201.

## Decisions

A **ValidatorDecision** records an approve/reject outcome by an actor
(human or automated). The canonical write path is
`POST /v1/payouts/{payoutId}/decisions`; `approve` and `reject` are
convenience aliases that synthesise a Decision under the hood and share
the same idempotency and state-machine guarantees.

## Endpoints

* [Create a Payout](/api-reference/payouts-create): `POST /v1/payouts`
* [Bulk-create Payouts](/api-reference/payouts-bulk-create): `POST /v1/payouts/bulk`
* [List Payouts](/api-reference/payouts-list): `GET /v1/payouts`
* [Retrieve a Payout](/api-reference/payouts-get): `GET /v1/payouts/{payoutId}`
* [Approve a Payout](/api-reference/payouts-approve): `POST /v1/payouts/{payoutId}/approve`
* [Reject a Payout](/api-reference/payouts-reject): `POST /v1/payouts/{payoutId}/reject`
* [Submit a Decision](/api-reference/payouts-decisions-create): `POST /v1/payouts/{payoutId}/decisions`
* [List Decisions](/api-reference/payouts-decisions-list): `GET /v1/payouts/{payoutId}/decisions`