The Intent State Machine
Learn about the status and lifecycle of PaymentIntents and SetupIntents.
Asynchronous payment flows are complex to manage because they depend on customer interactions that happen outside of your application. PaymentIntentsThe Payment Intents API is a new way to build dynamic payment flows. It tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods. and SetupIntentsThe Setup Intents API is a new way to build dynamic flows for collecting payment method details for future payments. It tracks the lifecycle of a payment setup flow and triggers additional authentication steps when required by regulatory mandates or by the payment method itself. simplify this by keeping track of the status of the payment or setup flow. The PaymentIntent and SetupIntent objects act as the single source of truth in the lifecycle of the flow.
An intent manages a dynamic, multi-step flow.
The goal of an intent is to get to a status of succeeded, which requires these steps:
- Create the intent
- Attach a valid payment method
- ConfirmConfirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects. the intent
The intent may then require additional steps of authentication or a new payment method in case of network failure or incorrect payment details. This state is reflected in the status of the intent.
Intent statuses
There are six values for status that apply to both PaymentIntents and SetupIntents:
| Status | Description |
|---|---|
requires_payment_method
|
When you create an intent, it has a status of requires_payment_method until you attach a payment method. |
requires_confirmation
|
An intent with a payment method is ready to be confirmed. |
requires_action
|
When you confirm an intent, Stripe will take advantage of any available optimizations (such as SCA exemptions for PaymentIntents) to complete the flow without making the customer take additional actions. If the payment method requires additional actions, such as authenticating with 3D Secure, the intent will have a status of requires_action. |
processing
|
Once required actions are handled, the intent moves to processing. |
canceled
|
You can cancel a PaymentIntent or SetupIntent at any point before it is succeeded.
This invalidates the intent for future confirmation, and cannot be undone. For PaymentIntents, cancellation also reverses any uncaptured funds.
|
succeeded
|
An intent with a status of succeeded means that the flow it is driving is complete.
For SetupIntents, this means that the setup was successful and the payment method is optimized for future payments. For PaymentIntents, this means the funds are in your account. After a PaymentIntent succeeds, use the Refunds API if you need to refund the customer. |
The flexibility of the intent state machine means that PaymentIntents and SetupIntents can support a wide range of payment flows with a unified integration. Take a look at some example use cases to find a relevant flow for your application.
There is an additional status that only applies to PaymentIntents:
| Status | Description |
|---|---|
requires_capture
|
If you want to separate authorize and capture to place a hold on a card, set capture_method to manual when creating the PaymentIntent. Then call confirm to authorize the card and capture when you're ready to capture the funds.
|