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.
requires_payment_method
When the PaymentIntent is created, it has a status of
requires_payment_method until a payment method is attached.
We recommend creating the PaymentIntent as soon as you know how much you want to charge, so that Stripe can record all the attempted payments.
requires_confirmation Optional
After the customer provides their payment information, the PaymentIntent is ready to be confirmed.
In most integrations, this state is skipped because payment method information is submitted at the same time that the payment is confirmed.
requires_action
If the payment requires additional actions, such as authenticating with
3D Secure
, the PaymentIntent has a status of requires_action.
processing
Once required actions are handled, the PaymentIntent moves to processing. While for some payment methods (e.g., cards) processing can be quick, other types of payment methods can take up to a few days to process.
succeeded
A PaymentIntent with a status of succeeded means that the payment flow it is driving is complete.
The funds are now in your account and you can confidently fulfill the order. If you need to refund the customer, you can use the Refunds API.
requires_payment_method
If the payment attempt fails (for example due to a decline), the PaymentIntent's status returns to requires_payment_method.
canceled
You may cancel a PaymentIntent at any point before it is processing or succeeded. This invalidates the PaymentIntent for future payment attempts, and cannot be undone. If any funds have been held, cancellation returns those funds.
requires_payment_method
When the SetupIntent is created, it has a status of
requires_payment_method until a payment method is attached.
requires_confirmation Optional
After the customer provides their payment method information, the SetupIntent is ready to be confirmed.
In most integrations, this state is skipped because payment method information is submitted at the same time that the SetupIntent is confirmed.
requires_action
If the setup requires additional actions, such as authenticating with
3D Secure
, the SetupIntent has a status of requires_action.
processing
Once required actions are handled, the SetupIntent moves to processing. While for certain payment methods (e.g., cards) processing can be quick, other payment methods can take up to a few days to process.
succeeded
A SetupIntent with a status of succeeded means that the setup is successful.
You may now attach this payment method to a Customer object and use this payment method for future payments.
requires_payment_method
If the setup fails, SetupIntent's status returns to requires_payment_method.
canceled
You can cancel a SetupIntent at any point before it is processing or succeeded.
