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

# Payout lifecycle

> Understand how payouts move from creation to completion, including status transitions, required actions, and failure states.

Every payout moves through a defined lifecycle from **creation** to **completion**.
Statuses reflect the current state of the payout and whether **action is required**, **approval is pending**, or **funds are in motion**.

## Lifecycle overview

Payouts move through four phases:

1. **Requires action** — `RequiresPayeeInfo`, `RequiresPayoutMethod`
2. **Ready** — `NeedsApproval`, `ReadyToProcess`
3. **In progress** — `Processing`
4. **Final states** — `Succeeded`, `Failed`, `Canceled`

## Status definitions

### RequiresPayeeInfo

<Badge stroke color="yellow" size="sm" icon="user">Action required</Badge>

The payout is missing required recipient details.

This occurs when:

* Payee information is incomplete
* A payout link has been sent but not completed

How to resolve:

* Update the payee with required details
* Or complete the payout link

***

### RequiresPayoutMethod

<Badge stroke color="yellow" size="sm" icon="landmark">Action required</Badge>

The payout does not have a valid payout method selected.

This occurs when:

* No payout method is available for the payee
* Existing methods are incomplete or incompatible

How to resolve:

* Add or update a payout method
* Or collect details via a payout link

***

### NeedsApproval

<Badge stroke color="blue" size="sm" icon="clipboard-check">Approval</Badge>

The payout requires approval before it can be processed.

This is typically used for:

* Internal review workflows
* High-value or sensitive payouts

Once approved, the payout moves to **ReadyToProcess** or one of the action required statuses if information is missing.

***

### ReadyToProcess

<Badge stroke color="blue" size="sm" icon="circle-check">Ready</Badge>

All required information is complete and any approvals have been satisfied.

At this stage:

* The payout is fully validated
* It is eligible to be sent

The payout will move to **Processing** when execution begins.

***

### Processing

<Badge stroke color="orange" size="sm" icon="spinner">In progress</Badge>

The payout has been submitted and is being processed through the selected payout method.

During this stage:

* Funds are in transit
* External payment networks may be involved
* Status updates occur asynchronously

No action is required while processing.

***

### Succeeded

<Badge stroke color="green" size="sm" icon="circle-check">Delivered</Badge>

The payout has been completed and funds have been delivered to the recipient.

At this stage:

* Final status is confirmed
* Receipts and remittance details are available
* The payout is ready for reconciliation

***

### Failed

<Badge stroke color="red" size="sm" icon="circle-x">Failed</Badge>

The payout could not be completed.

Common causes:

* Invalid or incorrect recipient details
* Rejection by the destination bank or network
* Compliance or processing issues

Next steps:

* Review the failure reason
* Correct any issues
* Retry the payout if appropriate

***

### Canceled

<Badge stroke color="gray" size="sm" icon="ban">Canceled</Badge>

The payout was canceled and will not be processed.

This can occur when:

* A user cancels the payout before processing
* A workflow or system action stops execution

Canceled payouts are final and will not be sent.

***

## State transitions

Payouts move forward as requirements are met and processing progresses.

Typical transitions include:

* **NeedsApproval** → **RequiresPayeeInfo** / **RequiresPayoutMethod** → **ReadyToProcess**
* **RequiresPayeeInfo** → **ReadyToProcess** (if details are completed directly)
* **ReadyToProcess** → **Processing** → **Succeeded**
* **Processing** → **Failed**
* **ReadyToProcess** → **Canceled**

Transitions are driven by:

* Data completeness
* Approval workflows
* Execution and external network responses

***

## Webhooks and status updates

Payout status changes are communicated via **webhooks**.

Use webhooks to:

* Track payout progress in real time
* Trigger internal workflows
* Handle failures and retries

Each status update corresponds to a lifecycle transition.

***

## Summary

* Payouts move through **clear phases** from required actions to final states
* **RequiresPayeeInfo** and **RequiresPayoutMethod** indicate missing data
* **NeedsApproval** introduces optional approval workflows
* **Processing** reflects funds in motion
* **Succeeded**, **Failed**, and **Canceled** are final states

Understanding the lifecycle helps you **build reliable workflows**, **handle edge cases**, and **maintain accurate reconciliation**.