Overview - Cleff API

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: POST /v1/payouts
Bulk-create Payouts: POST /v1/payouts/bulk
List Payouts: GET /v1/payouts
Retrieve a Payout: GET /v1/payouts/{payoutId}
Approve a Payout: POST /v1/payouts/{payoutId}/approve
Reject a Payout: POST /v1/payouts/{payoutId}/reject
Submit a Decision: POST /v1/payouts/{payoutId}/decisions
List Decisions: GET /v1/payouts/{payoutId}/decisions

⌘I