Fundamentals of the PaymentIntents and PaymentMethods APIs
Tags: stripe, webdev, tutorial, stripefundamentals
Published: 2021-10-28 17:04:34

*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](https://twitter.com/charlesw_dev) will kick this series by introducing two Stripe APIs you'll encounter: [`PaymentIntents`](https://stripe.com/docs/payments/payment-intents) and [`PaymentMethods`](https://stripe.com/docs/payments/payment-methods).*

### 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`](https://stripe.com/docs/payments/payment-methods) and [`PaymentIntents`](https://stripe.com/docs/payments/payment-intents) 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`](https://stripe.com/docs/payments/payment-methods) 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. 


![Credit card being saved as a PaymentMethod object using the Stripe PaymentMethods API](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/orci0pmuhlhhufewwrrj.png)

####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](https://stripe.com/docs/api/payment_intents/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.

![Transaction details being saved as a PaymentIntent by the PaymentIntents API](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gq5iqppt0hqbkajscpzv.png)

####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](https://stripe.com/docs/strong-customer-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](https://stripe.com/docs/payments/checkout) or [Payment Links](https://stripe.com/docs/payments/payment-links), Stripe handles the creation and management of `PaymentIntents` and `PaymentMethods` for you in the background!)

![Transaction payment details are saved as a PaymentIntent, the method of payment is saved as a PaymentMethod and attached to the PaymentIntent before being sent to the card/bank network](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tamsq3af8s7bijt5ee7w.png)

####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 

****

[![Build an integration using the integration builder](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rzuq6iubf4348lohitil.png)](https://stripe.com/docs/payments/quickstart)

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.](https://stripe.com/docs/payments/quickstart) walks through the many supported languages for client and server-side code.

You can learn more about integrating PaymentIntents in this [Stripe Developers video](https://www.youtube.com/watch?v=WG4ehXSEpz4). {% youtube WG4ehXSEpz4 %}

####Related resources:
- [The Payment Intents API](https://stripe.com/docs/payments/payment-intents)
- [Payment Methods API](https://stripe.com/docs/payments/payment-methods)
- [Strong Customer Authentication readiness](https://stripe.com/docs/strong-customer-authentication)
- [Stripe Checkout](https://stripe.com/docs/payments/checkout)
- [Share a payment link](https://stripe.com/docs/payments/payment-links) 
- [Custom payment flow](https://stripe.com/docs/payments/quickstart)

In our next post in the Stripe Payment Fundamentals series, we’ll dive into the [PaymentIntent lifecycle](https://stripe.com/docs/payments/intents) in detail. 

###Next up: Payment lifecycle fundamentals
In our next post in the Stripe Payment Fundamentals series, we’ll dive into the [`PaymentIntent` lifecycle](https://stripe.com/docs/payments/intents) in detail.

📣[ Follow us on Twitter](https://twitter.com/stripedev)
💬 [Join the official Discord server](https://stripe.com/go/developer-chat)
📺 Subscribe to our [Youtube channel](https://www.youtube.com/stripedevelopers)
📧 [Sign up for the Dev Digest](https://go.stripe.global/dev-digest)