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. PaymentIntents and SetupIntents 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
    • Confirm 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 status icon requires_payment_method When you create an intent, it has a status of requires_payment_method until you attach a payment method.
    requires_confirmation status icon requires_confirmation An intent with a payment method is ready to be confirmed.
    requires_action status icon 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 status icon processing Once required actions are handled, the intent moves to processing.
    canceled status icon 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 status icon 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 status icon 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.

    Next steps

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    On this page