Skip to main content
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.
Last modified on March 29, 2026