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 allow businesses to prepare for Strong Customer Authentication (SCA) by implementing Dynamic 3D Secure. Later this year, PaymentIntents will support 3D Secure 2 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 power 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:
- When you create a new PaymentIntent, it starts with the
requires_payment_methodstatus, which indicates that it is waiting for payment method information.
- When the customer supplies payment method information, the PaymentIntent’s status advances to
requires_confirmationuntil your application confirms that it should attempt to perform the charge.
- 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_actionand filling the
next_actionproperty with the relevant information that your application needs to help the customer complete the next step.
- 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
- 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_payment_method. 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 authorization and capture steps, the PaymentIntent’s state changes to
requires_captureafter 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.
To learn more about PaymentIntents, read more: