Transition to the Payment Intents and Payment Methods APIs (2024)

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 local payment methods. If you currently handle any local payment methods using the Sources API, you must migrate them to the Payment Methods API. We’ll send email communication with more information about this end of support.

While we don’t plan to turn off support for card payment methods, we still recommend that you migrate them to the Payment Methods and Payment Intents APIs. For more information about migrating card payment methods, see Migrating to the Payment Intents API.

Transitioning to the Payment Methods API

The main difference between the Payment Methods and Sources APIs is that Sources describes transaction state through the status property. That means that each Source object must transition to a chargeable state before it can be used for a payment. In contrast, a PaymentMethod is stateless, relying on the PaymentIntent object to represent payment state.

After you choose the API to integrate with, our guide to payment methods can help you determine the right payment method types to support for your customers.

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 are most relevant. You can enable any payment method available to you within the Dashboard. Activation is generally instantaneous and does not require additional contracts nor include a lengthy process.

Migrate local payment methods from the Sources API to the Payment Intents API

To migrate your integration for local payment methods, update your server and front end to use the PaymentIntents API. There are three typical integration options:

• Redirect to Stripe Checkout for your payment flow.
• Use the Stripe Payment Element on your own payment page.
• Build your own form and use the Stripe JS SDK to complete the payment.

If you use Stripe 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 local 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.

Mapping fields

If you use the Payment Element or your own form, you must remap Source fields to PaymentIntent fields. The specific fields depend on the payment method.

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 statuses—you only need to check the status of the PaymentIntent or the Checkout Session after you confirm it on the front end.

Always confirm the status of the PaymentIntent by fetching it on your server or listening for the webhooks 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 continue to call the Refunds API with a Charge that the PaymentIntent creates. The ID of the Charge is accessible on the latest_charge parameter.

Alternatively, you can provide the PaymentIntent ID to the Refunds API instead of the Charge.

Error handling

Previously, you had to handle errors on the Sources. With PaymentIntents, instead of checking for errors on a Source, you 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 new event types. The following table shows some examples.

Compatibility with legacy card objects

If you previously collected card customer payment details with Stripe using cards or Sources, you can start using the Payment Methods API immediately without migrating any payment information.

Compatible payment instruments that have been saved to a Customer are usable in any API that accepts a PaymentMethod object. For example, you can use a saved card as a PaymentMethod when creating a PaymentIntent:

curl https://api.stripe.com/v1/payment_intents \ -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \ -d "payment_method_types[]"=card \ -d amount=1099 \ -d currency=usd \ -d customer=
{{CUSTOMER_ID}} \ -d payment_method=
{{CARD_ID}}

Remember to provide the customer ID that your compatible payment instrument is saved to when attaching the object to a PaymentIntent.

You can retrieve all saved compatible payment instruments through the Payment Methods API.

{ "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "card", "address_city": "San Francisco", "address_country": "US", "address_line1": "1234 Fake Street", "address_line1_check": null, "address_line2": null, "address_state": null, "address_zip": null,

{ "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "payment_method", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "1234 Fake Street", "line2": null, "postal_code": null,

Note that with this compatibility, no new objects are created; the Payment Methods API provides a different view of the same underlying object. For example, updates to a compatible payment instrument through the Payment Methods API is visible through the Sources API and vice versa.