In a modern Stripe integration, every payment uses an object called a PaymentIntent. As its name suggests, it represents your intent to collect a payment. This object tracks the steps you go through along the way to fulfilling that intent.
For instance, suppose a customer clicks a Check out button with a 100 USD item in their cart. They haven’t bought it yet, and they might never buy it (maybe at some point they abandon the payment flow, or their card issuer declines the payment). But clicking Check out indicates their intent to buy—and you intend to help them. At that point, an integration creates a
PaymentIntent object in the amount of 100 USD to track the rest of the process.
PaymentIntent’s path to success goes through several statuses—here’s a simplified version:
PaymentIntent starts with the status
requires_payment_method. To move it forward, Stripe needs details about the customer’s payment method—either a card number or credentials for some other payment system.
An integration represents these details using an API object called a PaymentMethod. In some integrations, you write the code that creates that object and attaches it to the
PaymentIntent. In others, Stripe gathers the details and does the work for you.
The next status is
requires_confirmation. In an interactive payment flow, the customer must confirm that they intend to pay—and that they intend to do it using the method they provided. In a one-time online payment, this usually happens when they click the Pay button.
When the customer clicks Pay or otherwise confirms their intent, an integration notifies Stripe with an API call. In some integrations, you write the code that makes this call. Stripe provides drop-in UI elements, called Stripe Elements, to make this easier while still providing flexibility to build a custom integration. In other integrations, like a Stripe Checkout or Payment Links integration, Stripe makes the call and handles the next steps. There are many ways to integrate Stripe and combine different objects to handle your use case. Learn more about integration options for online payments.
Processing and success
The intent’s state is now
processing, and at this point Stripe attempts to process the payment.
Stripe always does this part for you—and it can have several steps. (For credit cards, these steps are part of how cards work.) As we work through the steps, we update the intent’s state with the outcome: either
succeeded or back to
requires_payment_method if it fails.
When we’re done, one last object comes into play: the Event. We use
Event objects to represent activity. In this case, the activity might be “the charge succeeded” or “the charge failed.” In some integrations, you write custom code to respond to events using webhooks. In others, such as Checkout or Payment Links integrations, Stripe listens for the event and provides a pre-written response.