Collect payment details before creating an Intent

You can customize the Payment Element’s layout (accordion or tabs) to fit your checkout interface. For more information about each of the properties, see elements.create.

const paymentElement = elements.create('payment', {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
    radios: true,
    spacedAccordionItems: false
  }
});

The following image is the same Payment Element rendered using different layout configurations:

Payment Element layouts

Now that you’ve added the Payment Element to your page, you can customize its appearance to make it fit your design. To learn more about customizing the Payment Element, see Elements Appearance API.

Customize the Payment Element

You can configure the Payment Element to save your customer’s payment methods for future use. This section shows you how to integrate the saved payment methods feature, which enables the Payment Element to:

• Prompt buyers for consent to save a payment method
• Save payment methods when buyers provide consent
• Display saved payment methods to buyers for future purchases
• Automatically update lost or expired cards when buyers replace them

Save payment methods.

Reuse a previously saved payment method.

Enable saving the payment method in the Payment Element

Create a CustomerSession on your server by providing the Customer ID and enabling the payment_element component for your session. Configure which saved payment method features you want to enable. For instance, enabling payment_method_save displays a checkbox that allows customers to save their payment details for future use.

You can specify setup_future_usage on a PaymentIntent or Checkout Session to override the default behavior for saving payment methods. This ensures that you automatically save the payment method for future use, even if the customer doesn’t explicitly choose to save it.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/create-customer-session' do
  customer_session = Stripe::CustomerSession.create({
    customer: 
{{CUSTOMER_ID}},
    components: {
        payment_element: {
          enabled: true,
          features: {
            payment_method_redisplay: 'enabled',
            payment_method_save: 'enabled',
            payment_method_save_usage: 'off_session',
            payment_method_remove: 'enabled',
          },
        },
      },
  })
  {
    customer_session_client_secret: customer_session.client_secret
  }.to_json
end

Your Elements instance uses the CustomerSession’s client secret to access that customer’s saved payment methods. Handle errors properly when you create the CustomerSession. If an error occurs, you don’t need to provide the CustomerSession client secret to the Elements instance, as it’s optional.

Create the Elements instance using the CustomerSession client secret. Then, use the Elements instance to create a Payment Element.

// Create the CustomerSession and obtain its clientSecret
const res = await fetch("/create-customer-session", {
  method: "POST"
});

const {
  customer_session_client_secret: customerSessionClientSecret
} = await res.json();

const elementsOptions = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  customerSessionClientSecret,
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret
// and CustomerSession's client secret obtained in a previous step
const elements = stripe.elements(elementsOptions);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

When confirming the PaymentIntent, Stripe.js automatically controls setting setup_future_usage on the PaymentIntent and allow_redisplay on the PaymentMethod, depending on whether the customer checked the box to save their payment details.

Enforce CVC recollection

Optionally, specify require_cvc_recollection both when creating the PaymentIntent and when creating Elements to enforce CVC recollection when a customer is paying with a card.

Detect the selection of a saved payment method

To control dynamic content when a saved payment method is selected, listen to the Payment Element change event, which is populated with the selected payment method.

paymentElement.on('change', function(event) {
  if (event.value.payment_method) {
    // Control dynamic content if a saved payment method is selected
  }
})

As the customer performs actions that change the payment details (for example, applying a discount code), update the Elements instance to reflect the new values. Some payment methods, like Apple Pay and Google Pay, show the amount in the UI, so make sure it’s always accurate and up to date.

async function handleDiscountCode(code) {
  // On the server, validate that the discount code is valid and return the new amount
  const {newAmount} = await fetch("/apply-discount", {
      method: "POST",
      headers: {"Content-Type": "application/json"},
      body: JSON.stringify({code}),
    });
  elements.update({amount: newAmount});
}

The Elements object accepts additional options that influence payment collection. Based on the options provided, the Payment Element displays available payment methods from those you’ve enabled. Learn more about payment method support.

If you want to build a multi-page checkout or collect payment method details before running additional validations, see Build a two-step checkout flow. With this flow, you create a ConfirmationToken on the client to collect payment details and then use it to create a PaymentIntent on the server.

Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard, a custom webhook, or a partner solution to receive these events and run actions, like 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 also helps you accept more payment methods in the future. Learn about the differences between all supported payment methods.

• Handle events manually in the Dashboard

  Use the Dashboard to View your test payments in the Dashboard, send email receipts, handle payouts, or retry failed payments.

• Build a custom webhook

  Build a custom webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

• Integrate a prebuilt app

  Handle common business events, such as automation or marketing and sales, by integrating a partner application.