How PaymentIntents and SetupIntents work

Learn how PaymentIntents and SetupIntents work within the payment flow.

The main difference between the Payment Intents API and Setup Intents API is their purpose. You use the Payment Intents API to collect payment and charge a customer immediately. It creates a charge and processes a transaction to collect funds. You use Setup Intents API, on the other hand, to collect and save payment method details for future use without creating a charge. It sets up payment credentials without processing a payment.

Because both immediate charges and saving a payment method can require asynchronous customer steps, these APIs use the same state-machine pattern.

Payment Intents API	Setup Intents API
Creates an immediate charge	Creates no charge
Tracks a payment’s lifecycle	Tracks the progress of setting up a payment method
Uses 3D secure to authenticate the customer for the applicable transaction	Uses 3D secure to authenticate a payment method without charging it, and creates a mandate or agreement for future charges

A PaymentIntent tracks the lifecycle of a payment from creation through checkout, triggering additional authentication steps when required.

Requires payment method

After you create the PaymentIntent, its status is requires_payment_method until you attach a payment method. Create the PaymentIntent as soon as you know the amount to charge so Stripe can record all attempted payments.

Requires confirmation

After your customer provides payment information, the PaymentIntent enters the requires_confirmation status and is ready to confirm. Most integrations skip this state because they submit payment method information when 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.

API changes

Versions of the API before 2019-02-11 show requires_source instead of requires_payment_method and requires_source_action instead of requires_action.

Processing

After required actions are handled, the PaymentIntent moves to processing for asynchronous payment methods, such as bank debits. These types of payment methods can take up to a few days to process. Other payment methods, such as cards, are processed more quickly and don’t go into the processing status.

If you’re separately authorizing and capturing funds, your PaymentIntent can instead move to requires_capture. In that case, attempting to capture the funds moves it to processing or succeeded depending on the payment method.

Succeeded

A PaymentIntent with a status of succeeded means that the payment flow it’s 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. If the payment attempt fails (for example due to a decline), the PaymentIntent’s status returns to requires_payment_method so that the payment can be retried.

Canceled

You can cancel a PaymentIntent at any point before it’s in a processing or succeeded state. Canceling it invalidates the PaymentIntent for future payment attempts, and can’t be undone. If any funds have been held, cancellation releases them. You can cancel a PaymentIntent in the processing state when the associated payment method is ACH, ACSS, AU BECS, BACS, NZ BECS, or SEPA. However, it might fail due to a limited and varying cancellation time window.

PaymentIntents might also be automatically transitioned to the canceled state after they have been confirmed too many times.