Payouts and settlements

Payout versus settlement

A payout moves value from a wallet to a specified payout destination. A settlement summarizes a wallet operating period and passes through review and execution. Neither is an unconditional instant action; both have states, approvals, and permitted transitions.

Payout states

A payout starts as pending and can move through under review, approved, executing, and executed. Rejected, failed, and cancelled states are also present. Do not call execute before approval. Failed is not always terminal; the model can allow retry or cancellation according to policy.

Settlement states

A settlement starts pending, then becomes approved, rejected, or cancelled. After approval it moves to executing and then executed or failed. Read the resource state from the API rather than deriving it from buttons displayed in your interface.

Idempotency keys

Creating payouts and settlements requires idempotency_key in the JSON body. Approval, rejection, and execution are separate intents; do not retry them blindly without reading current state. On 409, reload the resource before deciding what to do next.

Reporting and audit

Use payout and settlement reports for the relevant period and retain approver, operator, rejection reason, and cancellation evidence. Do not rewrite historical records to correct an error; issue the appropriate compensating movement and preserve an auditable trail.