Migrate to the Payment Intents and Payment Methods APIs
Learn how to transition from the Sources and Tokens APIs to the Payment Methods API.
The Payment Methods API replaces the existing Tokens and Sources APIs as the recommended way for integrations to collect and store payment information. It works with the Payment Intents API to create payments for a wide range of payment methods.
We plan to turn off Sources API support for card payments. If you currently handle any card payment methods using the Sources API, you must migrate them to the Payment Intents API. We’ll send email communication with more information about the end of support for the Sources API.
Migrate to the Payment Intents API
To migrate your integration, update your server and front end to use the Payment Intents API. Typical integration options include:
- Redirect to Stripe Checkout for your payment flow.
- Use the Stripe Payment Element on your own payment page.
- Build a custom form and use the Stripe JS SDK to complete the payment.
If you use Checkout or the Payment Element, you can add and manage most payment methods from the Stripe Dashboard without making code changes.
For specific information about integrating a card payment method using the Payment Methods API, see the instructions for that payment method in the payment methods documentation. The following table provides a high-level comparison of the different payment types.
| Old integration | Stripe Checkout | Payment Element | Custom form |
|---|---|---|---|
| Low complexity | Medium complexity | High complexity | |
| Create a Source on the front end or on the server. | Create a CheckoutSession on the server. | Create a PaymentIntent on the server. | Create a PaymentIntent on the server. |
| Authorize payment by loading a widget or redirecting to a third party. | Not needed | Pass the client secret to the front end and use the Stripe JS SDK to render a Payment Element to complete the payment. | Pass the client secret to the front end, use your own form to collect details from your customer, and complete the payment according to the payment method. |
| Confirm the source is chargeable and charge the Source. | Not needed | Not needed | Not needed |
Confirm that the Charge succeeded asynchronously with the charge.succeeded webhook. | Confirm that the Checkout session succeeded with the payment_intent.succeeded webhook. | Confirm that the PaymentIntent succeeded with the payment_intent.succeeded webhook. | Confirm that the PaymentIntent succeeded with the payment_intent.succeeded webhook. |
Continued use of Charge objects
A PaymentIntent object represents a payment in the new integration, and it creates a Charge when you confirm the payment on the front end. If you previously stored references to the Charge, you can continue to do so by fetching the Charge ID from the PaymentIntent after the customer completes the payment. However, we also recommend that you store the PaymentIntent ID.
Checking payment status
Previously, your integration should have checked both the status of the Source and the status of the Charge after each API call. You no longer need to check two objects—you only need to check the status of the PaymentIntent or the CheckoutSession after you confirm it on the front end.
| payment_intent.status | Meaning |
|---|---|
succeeded | The payment succeeded. |
requires_payment_method | The payment failed. |
requires_action | The customer hasn’t completed authorizing the payment, possibly due to a 3DS requirement. |
Always confirm the status of the PaymentIntent by fetching it on your server or listening for the webhook events on your server. Don’t rely solely on the user returning to the return_url that’s provided when you confirm the PaymentIntent.
Refunds
You can call the Refunds API using the PaymentIntent ID instead of the Charge ID.
Alternatively, you can continue to call the Refunds API with the ID of the Charge that the PaymentIntent creates. You can get the ID of the Charge from the latest_charge property.
Error handling
Previously, you had to handle errors on the Source. With PaymentIntents, you instead check for errors on the PaymentIntent when it’s created and after the customer has authorized the payment. Most errors on the PaymentIntent are of invalid_request_error type, returned in an invalid request.
When you migrate your integration, keep in mind that PaymentIntent error codes can differ from the corresponding error codes for Sources.
Webhooks
If you previously listened to Source events, you might need to update your integration to listen to events for other objects instead. The following table shows some examples.
| Old event | New Checkout event | New PaymentIntent event | Special instructions |
|---|---|---|---|
source.chargeable | Not applicable | Not applicable | |
source.failed | Not applicable | Not applicable | |
source.canceled | Not applicable | Not applicable | |
charge.succeeded | checkout.session.completed | payment_intent.succeeded | The charge.succeeded event is also sent, so you can continue listening for it instead of the others. |
charge.failed | Not applicable - The customer can re-attempt the payment on the same Checkout Session until it expires, at which point you receive a checkout.session.expired event. | payment_intent.payment_failed | The charge.failed event is also sent, so you can continue listening for it instead of the others. |
charge.dispute.created | charge.dispute.created | charge.dispute.created |
Transition to the Payment Methods API
The main difference between the Payment Methods and Sources APIs is that Sources describes the transaction state through the status property. That means that each Source object must transition to a chargeable state before you can use it for a payment. By contrast, a PaymentMethod is stateless, relying on the PaymentIntent object to represent payment state.
Note
The following table isn’t a comprehensive list of payment methods. If you integrate other payment methods with the Sources API, migrate them to the Payment Methods API as well.
| Flows | Payment Methods and Payment Intents APIs | Tokens or Sources with Charges APIs |
|---|---|---|
| Cards | Card payments | Deprecated |
| ACH Direct Debit | US bank account direct debits | Supported on Tokens; Not supported on Sources |
After you choose the API to integrate with, use the guide to payment methods to help you determine the right payment method types you need to support.
This guide includes detailed descriptions of each payment method and describes the differences in the customer-facing flows, along with the geographic regions where they’re most relevant. You can enable any payment method available to you within the Dashboard. Activation is generally instantaneous and doesn’t require additional contracts.
Migrate saved Sources to PaymentMethods
To continue using your existing customers’ credentials saved on Sources or on cards created with the Charges API, you must convert them to PaymentMethods using the data migration tool in the Stripe Dashboard.
To use a migrated PaymentMethod with the Payment Intents API, pass the PaymentMethod ID and the Customer ID when creating a PaymentIntent:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results