Payout lifecycle

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.

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

Action required 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

Action required 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

Approval 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

Ready 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

In progress 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

Delivered 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

Failed 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

Canceled 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.