Skip to main content
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.
Agents: fetch this page as plain markdown at https://docs.usecleff.com/api-reference/payouts.md.

​
Lifecycle

A Payout moves through an explicit state machine, from pending_approval to settled or one of its terminal states. Payouts carries the state diagram, every transition, and what to do in each state. Branch on status to decide what to do next: needs_approval, processing, in_transit, delivered, or one of the endings rejected, failed, returned and canceled. state keeps the full lifecycle for when you need the exact step, such as settled. delivered_at is when the money arrived in the Beneficiary’s account, or null until it does, so a payout you poll shows its arrival without a webhook. Branch on status maps each status to its state. provider, provider_payout_id, rail and rail_ref on a Payout describe the latest time it was sent; earlier sends are not exposed. rail names the network that carried the payment (ach, rtp, fednow or card), or is null until the provider reports one, and for a payout that never reached the provider.

​
Idempotency

POST /v1/payouts is idempotent on (Business, environment, idempotency key) within a 24-hour window. Send the key in the Idempotency-Key header or the idempotency_key body field. Resending the same request returns the original Payout with HTTP 200 instead of 201; reusing a key for a request that names different money is refused with 409 IDEMPOTENCY_CONFLICT. See Idempotency for the full contract.

​
Decisions

A Decision records an approve or reject verdict by a validator: a person on your team, or your own risk system calling the API. The canonical write path is POST /v1/payouts/{payoutId}/decisions; approve and reject are conveniences over it and share the same idempotency and state-machine guarantees. Pass the approval gate explains each.

​
Endpoints