Migrate to the Payment Element with the Payment Intents API

Accept many payment methods with a single Element.

Interested in subscriptions, tax, discounts, shipping, or currency conversion?

Migrate to the Payment Element with the Checkout Sessions API, an integration that manages subscriptions, tax, discounts, shipping, and currency conversion for you.

Previously, each payment method (cards, iDEAL, and so on) required a separate Element. By migrating to the Payment Element, you can accept many payment methods with a single Element.

PaymentIntents and SetupIntents each have their own set of migration guidelines. See the appropriate guide for your integration path, including example code. If your integration still uses the Charges API with tokens, first Migrate to the Payment Intents API before you use this guide.

If your existing integration uses the Payment Intents API to create and track payments or save card details during a payment, follow the steps below to use the Payment Element.

Enable payment methods

Caution

This integration path doesn’t support the related setting or pre-authorized debits that use the Automated Clearing Settlement System (the related setting). Also, if you create the deferred intent from the client-side, you can’t use customer_balance with dynamic payment methods because the PaymentIntent requires a customer-configured Account or Customer object, which the client-side flow doesn’t support. To use customer_balance, create the PaymentIntent server-side with an Account or Customer and return its client_secret to the client.

View your payment methods settings and enable the payment methods you want to support. You need at least one payment method enabled to create a PaymentIntent.

By default, Stripe enables cards and other prevalent payment methods that can help you reach more customers, but we recommend turning on additional payment methods that are relevant for your business and customers. See Payment method support for product and payment method support, and our pricing page for fees.

Update Elements instance Client-side

Next, update your client-side code to pass mode, currency, and amount when you create the Elements instance. For use with a PaymentIntent, set the mode to 'payment' and the currency and amount to what you’ll charge your customer.

Before

After

const stripe =
 Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const elements = stripe.elements();

const stripe =
 Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const options = {
 mode: 'payment',
 currency: 'usd',
 amount: 1099,
};
const elements = stripe.elements(options);

Optional Save payment details during a payment

Optional Additional Elements options Client-side

Add the Payment Element Client-side

You can now replace the Card Element and individual payment methods Elements with the Payment Element. The Payment Element automatically adjusts to collect input fields based on the payment method and country (for example, full billing address collection for the related setting Direct Debit) so you don’t have to maintain customized input fields anymore.

The following example replaces CardElement with PaymentElement:

checkout.html

Select a language

JavaScript

React

No results

<form id="payment-form">
 <div id="card-element">
 </div>
 <div id="payment-element">
 <!-- Mount the Payment Element here -->
 </div>
 <button id="submit">Submit</button>
</form>

checkout.js

Select a language

JavaScript

React

No results

const cardElement = elements.create("card");
cardElement.mount("#card-element");
const paymentElement = elements.create("payment");
paymentElement.mount("#payment-element");

If your payment flow already always collects details like the customer’s name or email address, you can prevent the Payment Element from collecting this information by passing the fields option when creating the Payment Element. If you disable the collection of a certain field, you must pass that same data back with stripe.confirmPayment.

Update your PaymentIntent creation call Server-side

The Payment Element allows you to accept multiple payment methods. You can manage payment methods from the Dashboard. Stripe handles the return of eligible payment methods based on factors such as the transaction’s amount, currency, and payment flow. We prioritize payment methods that increase conversion and are most relevant to the customer’s currency and location.

Any of the additional elements options passed when creating the Elements group in the earlier step should also be passed when creating the PaymentIntent.

Command Line

Select a language

curl

Ruby

Python

PHP

Java

Node.js

Go

.NET

Stripe CLI

No results

Caution

Each payment method needs to support the currency passed in the PaymentIntent and your business needs to be based in one of the countries each payment method supports. For more details about what’s supported, see the Payment method integration options.

Update the submit handler Client-side

Instead of using individual confirm methods like stripe.confirmCardPayment or stripe.confirmP24Payment, use stripe.confirmPayment to collect payment information and submit it to Stripe.

To confirm the PaymentIntent, make the following updates to your submit handler:

• Call await elements. submit() to trigger form validation and collect any data required for wallets .
• Optional: Move PaymentIntent creation to the submit handler. This way you only create the PaymentIntent when you’re sure of the final amount.
• Pass the elements instance you used to create the Payment Element and the clientSecret from the PaymentIntent as parameters to stripe. confirmPayment .

When called, stripe.confirmPayment attempts to complete any required actions, such as authenticating your customers by displaying a 3DS dialog or redirecting them to a bank authorization page. When confirmation is complete, users are directed to the return_url you configured, which normally corresponds to a page on your website that provides the status of the payment.

If you want to keep the same checkout flow for card payments and only redirect for redirect-based payment methods, you can set redirect to if_required.

The following code example replaces stripe.confirmCardPayment with stripe.confirmPayment:

Before

After

// Create the PaymentIntent and obtain clientSecret
const res = await fetch("/create-intent", {
 method: "POST",
 headers: {"Content-Type": "application/json"},
});

const {client_secret: clientSecret} = await res.json();

const handleSubmit = async (event) => {
 event.preventDefault();

 if (!stripe) {
 // Stripe.js hasn't yet loaded.
 // Make sure to disable form submission until Stripe.js has loaded.
 return;
 }

 setLoading(true);

 const {error} = await stripe.confirmCardPayment(clientSecret, {
 payment_method: {
 card: elements.getElement(CardElement)
 }
 });

 if (error) {
 handleError(error);
 }
};

Optional Recollect a CVC

When creating subsequent payments on a saved card, you might want to re-collect the CVC of the card as an additional fraud measure to verify the user.

Start by creating a PaymentIntent on your server with the amount, currency, the Account or Customer ID, and require_cvc_recollection. List the PaymentMethods associated with your customer to determine which ones to show for CVC re-collection.

After passing the PaymentIntent ’s client secret to the browser, you can re-collect CVC information with Stripe Elements on your client. Use the cardCvc Element to re-collect a CVC value from your customer, then confirm the payment from your client using stripe.confirmCardPayment. Set payment_method to your PaymentMethod ID, and payment_method_options[card][cvc] to your cardCvc Element.

client.js

const result = await stripe.confirmCardPayment(clientSecret, {
 payment_method: '{{PAYMENT_METHOD_ID}}',
 payment_method_options: {
 card: {
 cvc: cardCvcElement
 }
 },
});

if (result.error) {
 // Show error to your customer
 console.log(result.error.message);
} else {
 if (result.paymentIntent.status === 'succeeded') {
 // Show a success message to your customer
 // There's a risk of the customer closing the window before callback
 // execution. Set up a webhook or plugin to listen for the
 // payment_intent.succeeded event that handles any business critical
 // post-payment actions.
 }
}

A payment might succeed even with a failed CVC check. To prevent this, configure your Radar rules to block payments when CVC verification fails.

Handle post-payment events Server-side

Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard webhook tool or follow the webhook guide to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events is what enables you to accept different types of payment methods with a single integration.

In addition to handling the payment_intent.succeeded event, we recommend handling these other events when collecting payments with the Payment Element:

Test the integration

See Testing for additional information to test your integration.