Migrate to the Payment Element

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 in the next step. Stripe enables card payments by default so you can skip this step if you want to start with cards only. See the Payment method integration options page for information on product and payment method support.

The payment methods shown to customers during the checkout process are now included on the PaymentIntent. You can let Stripe pull payment methods from your Dashboard settings or you can list them manually. Regardless of the option you choose, know that the currency passed in the PaymentIntent filters the payment methods that the customer sees. For example, if you pass eur on the PaymentIntent and have OXXO enabled in the Dashboard, the customer won’t see OXXO because OXXO doesn’t support eur payments.

Stripe recommends using automatic_payment_methods because we evaluate the currency, payment method restrictions, and other parameters to determine the list of supported payment methods. We prioritize payment methods that increase conversion and are most relevant to the currency and customer’s location.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -H "Stripe-Version: 2022-08-01" \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "automatic_payment_methods[enabled]"=true \

Next, update your client-side code to pass the client_secret returned from the PaymentIntent or SetupIntent as the clientSecret option when you create the Elements instance.

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

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
};
const elements = stripe.elements(options);

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 SEPA Direct Debit) so you don’t have to maintain customized input fields anymore.

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.

Below is an example of replacing CardElement with PaymentElement:

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

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

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

Since you already passed in the clientSecret when creating the Elements instance, you no longer need to pass in clientSecret again when submitting the payment. stripe.confirmPayment also takes the Elements instance that was used to create the Payment Element instead of taking the individual Element object.

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. Users are directed to the return_url you configured once the confirmation is complete, which should correspond 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 without redirecting and only redirect for redirect-based payment methods, you can set redirect to if_required.

Below is an example of replacing stripe.confirmCardPayment with stripe.confirmPayment:

const {paymentIntent, error} = await stripe.confirmCardPayment(
  '{{CLIENT_SECRET}}', {
    payment_method: {
      card: cardElement,
      billing_details: {
        name: 'Jenny Rosen'
      }
    }
  }
);

const {error} = await stripe.confirmPayment({
  elements,
  confirmParams: {
    return_url: 'https://example.com/order/123/complete',
  },
  // Uncomment below if you only want redirect for redirect-based payments
  // redirect: 'if_required',
});

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 two other events when collecting payments with the Payment Element:

Use test payment details and the test redirect page to verify your integration. Click the tabs below to view details for each payment method.