A PaymentIntent is an object that represents your intent to collect a payment from a customer. It tracks the lifecycle of the payment through each stage of the process. Coupled with Elements and Stripe.js, PaymentIntents make it easier to accept payment methods that entail multiple steps.

PaymentIntents allows businesses to prepare for Strong Customer Authentication (SCA) by implementing Dynamic 3D Secure. When 3D Secure 2 becomes available in 2019, PaymentIntents will support this new flow automatically with no additional integration required. As soon as SCA requirements go into effect, PaymentIntents will dynamically trigger 3D Secure 2 when required and apply exemptions to SCA requirements when possible.

PaymentIntents also powers other products such as Terminal. In the future, we expect PaymentIntents to power all payment collection on Stripe.

The PaymentIntent lifecycle

Each PaymentIntent is an object that transitions through multiple states during use. A PaymentIntent reaches its final status (succeeded) when it completes one successful charge. If a charge performed with a PaymentIntent is unsuccessful, you may use the same PaymentIntent to attempt additional charges for the customer until one completes successfully.

The following are the stages through which a PaymentIntent typically progresses during a transaction:

1. When you create a new PaymentIntent, it starts with the requires_source status, which indicates that it is waiting for payment method information.
2. When the customer supplies payment method information, the PaymentIntent’s status advances to requires_confirmation until your application confirms that it should attempt to perform the charge.
3. When the customer uses payment methods that involve additional steps, such as prompting for additional credentials, the PaymentIntent tracks that for you–updating its status to requires_source_action and filling the next_source_action property with the relevant information that your application needs to help the customer complete the next step.
4. When the charge attempt is confirmed and there are no further actions left to perform, the charge proceeds and the PaymentIntent’s status progresses to processing.
5. If the charge completes successfully, the PaymentIntent is fulfilled and its status changes to succeeded. No further charges can be attempted by the PaymentIntent after it has completed one successful charge.

If payment fails at any stage during the process, the PaymentIntent’s status resets to requires_source. When it returns to the initial state, you can prompt the customer to try again–potentially with a different payment method, if desired. The entire history of charges attempted by a PaymentIntent is stored in the PaymentIntent’s charges property.

There are two additional states that can arise under certain circumstances:

• When you cancel a PaymentIntent, its status changes to canceled. You may not attempt additional charges on a PaymentIntent after cancellation.
• If your integration uses two-step card payments with separate authorize and capture steps, the PaymentIntent’s state changes to requires_capture after authorizing the charge. You must capture the charge within seven days or the PaymentIntent will be canceled.

Stripe.js and Elements integrate tightly with PaymentIntents, abstracting away much of the complexity of managing the PaymentIntent’s progression through each stage. Typically, steps like confirmation are performed by Stripe.js behind the scenes—eliminating the need for you to handle them in your application. If you want more granular control over the charge process, you may choose to take a more hands-on approach.

Next steps

To learn more about PaymentIntents, read more:

• PaymentIntents Quickstart
• PaymentIntents Usage
• PaymentIntents Migration Guide