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:
Requires action — RequiresPayeeInfo, RequiresPayoutMethodReady — NeedsApproval, ReadyToProcessIn progress — ProcessingFinal states — Succeeded, Failed, Canceled
Status definitions RequiresPayeeInfo 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 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 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 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 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 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 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 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 dataNeedsApproval introduces optional approval workflowsProcessing reflects funds in motionSucceeded , Failed , and Canceled are final states
Understanding the lifecycle helps you build reliable workflows , handle edge cases , and maintain accurate reconciliation . Last modified on March 29, 2026
