Fundamentals of the PaymentIntents and PaymentMethods APIs

Understanding how online payments work can be overwhelming. Developers must learn payment industry terminology, test the APIs, and choose a revenue model in order to complete a successful transaction. To guide you on this path, we’re introducing the Payment fundamentals series: A collection of articles released every few weeks where we address fundamental developer topics and explain how they work.

This week, Charles Watkins will kick this series by introducing two Stripe APIs you'll encounter: PaymentIntents and PaymentMethods.

Payment APIs and how are they used

To accept a payment, you need a way to represent the payment details and a way to handle the transaction itself — this is where PaymentMethods and PaymentIntents come in.

Your first thought might be:

Can I choose one or the other?

Not quite. You can have a PaymentMethod without a PaymentIntent, but you need that PaymentIntent to use those payment details represented by the PaymentMethod to complete a transaction. Similarly, a PaymentIntent without a PaymentMethod cannot be completed. PaymentMethods and PaymentIntents work together to turn payment details into a real-world transfer of funds.

Let’s dig into what they are and how they function.

What's the PaymentMethods API?

The PaymentMethods API lets you accept a variety of payment methods, from credit cards to bank accounts to vouchers, by creating a representation of the payment in the form of a PaymentMethod object.

How the PaymentMethods API works:

1. Customer enters payment details on a website
2. Payment details are sent to Stripe
3. Stripe's PaymentMethods API creates a PaymentMethod object
4. PaymentMethod object can be used to refer to real-life payment details

What's the PaymentIntents API?

The PaymentIntents API creates a PaymentIntent object which manages a transaction’s details — such as the transaction amount and currency — and its payment flow (Note: We’ll cover the details of how the payment flow works in our next blog post.)

Different methods of payment have different requirements and timelines, and the PaymentIntents API helps us navigate them.

How the PaymentIntents API works:

1. Customer attempts a transaction on a website
2. Transaction details are sent to Stripe
3. Stripe API creates a PaymentIntent Object
4. PaymentIntent object can be used to authenticate and complete a transaction with card/bank networks

How do they work together?

When your customer submits their payment details to Stripe, you use the PaymentMethods API to store them. Next, you’ll create a PaymentIntent object and attach the PaymentMethod to the PaymentIntent. Finally, you complete the PaymentIntent by confirming it. Confirming the PaymentIntent authorizes the payment with the card and bank networks.

The PaymentIntent keeps track of the payment’s status throughout its lifecycle, so that you can take the appropriate next steps to complete it if necessary.

Why is it important to track the payment’s lifecycle?
The time to payment completion can vary by method of payment. For instance, credit card transactions have immediate outcomes, but a bank debit can take days.

In addition, payment flows may have regional differences, such as how some credit card transactions in Europe include 3D Secure authentication. The PaymentIntent object accounts for differences in payment methods by keeping track of a payment status and indicating the next required action to complete the payment.

(Note: If you’re using Stripe Checkout or Payment Links, Stripe handles the creation and management of PaymentIntents and PaymentMethods for you in the background!)

The Lifecycle of a Payment:

1. Customer attempts a transaction and enters payment details
2. Transaction and payment method details are sent to Stripe from the app
3. Transaction details go to the PaymentIntents API; payment method details are sent to the PaymentMethods API
4. The PaymentIntents API creates a PaymentIntent object while the PaymentMethods API creates a PaymentMethod object
5. The PaymentMethod object is attached to the PaymentIntent object
6. The PaymentIntents API sends the transaction to the card or bank network to be confirmed or completed

Now that you’ve learned about the PaymentIntents and PaymentMethods APIs, it's time to build your own integration.

Stripe’s quick start integration builder. walks through the many supported languages for client and server-side code.

You can learn more about integrating PaymentIntents in this Stripe Developers video.

Related resources:

• The Payment Intents API
• Payment Methods API
• Strong Customer Authentication readiness
• Stripe Checkout
• Share a payment link
• Custom payment flow

In our next post in the Stripe Payment Fundamentals series, we’ll dive into the PaymentIntent lifecycle in detail.

Next up: Payment lifecycle fundamentals

In our next post in the Stripe Payment Fundamentals series, we’ll dive into the PaymentIntent lifecycle in detail.

📣 Follow us on Twitter
💬 Join the official Discord server
📺 Subscribe to our Youtube channel
📧 Sign up for the Dev Digest