Payment 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 payment moves through a defined lifecycle from creation to completion. Statuses reflect the current state of the payment and whether action is required, authorization is complete, or funds are in motion.

​

Lifecycle overview

Payments move through four phases:

1. Requires action — RequiresPaymentMethod, RequiresAction
2. Ready — Authorized
3. In progress — Processing
4. Final states — Succeeded, Failed, Canceled

​

Status definitions

​

RequiresPaymentMethod

Action required The payment does not have a valid payment method. This occurs when:

• No payment method has been provided
• The selected method is incomplete or not supported

How to resolve:

• Provide a payment method through a hosted or embedded flow
• Or update the payment request configuration

---

​

RequiresAction

Action required The payment is waiting for the payer to complete an action. This occurs when:

• The payer has not completed the payment flow
• Additional steps are required (e.g. entering details or confirming payment)

How to resolve:

• Direct the payer to complete the payment
• Ensure the payment experience is accessible and complete

---

​

Authorized

Authorized The payment method has been successfully authorized. At this stage:

• Required payer consent or authorization has been captured
• The payment is eligible to be processed

For some methods (such as cards), authorization and processing may occur almost immediately.

---

​

Processing

In progress The payment has been submitted and is being processed. During this stage:

• Funds are in transit or being confirmed
• External payment networks may be involved
• Status updates occur asynchronously

No action is required while processing.

---

​

Succeeded

Completed The payment has completed successfully. At this stage:

• The payer has been charged
• Funds are settled or in the process of settlement
• The payment is ready for reconciliation

---

​

Failed

Failed The payment could not be completed. Common causes:

• Invalid or incorrect payment details
• Rejection by the bank or payment network
• Authorization or processing issues

Next steps:

• Review the failure reason
• Correct any issues
• Retry the payment if appropriate

---

​

Canceled

Canceled The payment was canceled and will not be processed. This can occur when:

• A user cancels the payment request
• The payment is no longer needed
• A workflow or system action stops execution

Canceled payments are final and will not be processed.

---

​

State transitions

Payments move forward as requirements are met and processing progresses. Typical transitions include:

• RequiresPaymentMethod → RequiresAction → Authorized
• RequiresAction → Authorized (once the payer completes the flow)
• Authorized → Processing → Succeeded
• Processing → Failed
• Authorized → Canceled

Transitions are driven by:

• Payer interaction
• Data completeness
• Payment method behavior
• External network responses

---

​

Webhooks and status updates

Payment status changes are communicated via webhooks. Use webhooks to:

• Track payment progress in real time
• Trigger internal workflows
• Handle failures and retries

Each status update corresponds to a lifecycle transition.

---

​

Summary

• Payments move through clear phases from required actions to final states
• RequiresPaymentMethod and RequiresAction indicate missing input or payer interaction
• Authorized confirms payment method approval
• 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.