Stripe Payment Element

Accept payment methods from around the globe with a secure, embeddable UI component.

The Payment Element is a UI component for the web that lets you accept more than 100 payment methods, validates input, and handles errors. Use it alone or with other elements in your web app’s front end.

Customer location

Size

Theme

Layout

This demo only displays Google Pay or Apple Pay if you have an active card with either wallet.

Compatible APIs

Stripe offers two core payments APIs compatible with Elements. We recommend the Checkout Sessions API for most integrations.

• Use the Checkout Sessions API to build your checkout flow. Checkout Sessions covers similar use cases as Payment Intents, including basic payments using price_data or full checkout with line items, tax, discounts, shipping, subscriptions, or Adaptive Pricing (only available with Checkout Sessions). Build a checkout page with the Checkout Sessions API.
• The Payment Intents API is a lower-level API that models only the payment step. You pass in a final amount and build all checkout logic yourself, including tax calculation, discounts, shipping, subscriptions, and currency conversion. Use Payment Intents only if you want to deeply own your checkout state and build these features yourself. Build a custom integration from scratch with the Payment Intents API.

Build an advanced integration with Payment Element and Checkout Sessions

Build an integration with the Payment Element using the Checkout Sessions API.

Build an integration with Payment Element and Payment Intents

Use the Payment Intents API to build your own checkout flow.

Clone a sample app on GitHub HTML · React · Vue

View the Stripe.js reference

Combine elements

The Payment Element interoperates with other elements. For instance, this form uses one additional element to autofill checkout details, and another to collect the shipping address.

Note

You can’t remove the Link legal agreement because it’s required to ensure compliance with proper user awareness of terms of services and privacy policies. The terms object doesn’t apply to the Link legal agreement.

Payment form combining multiple elements

For the complete code for this example, see Add Link to an Elements integration.

You can also combine the Payment Element with the Express Checkout Element. In this case, wallet payment methods such as Apple Pay and Google Pay are only displayed in the Express Checkout Element to avoid duplication.

Payment methods

Stripe enables certain payment methods for you by default. We might also enable additional payment methods after notifying you. Use the Dashboard to enable or disable payment methods at any time. With the Payment Element, you can use Dynamic payment methods to:

• Manage payment methods in the Dashboard without coding
• Dynamically display the most relevant payment options based on factors such as location, currency, and transaction amount

For instance, if a customer in Germany is paying in EUR, they see all the active payment methods that accept EUR, starting with ones that are widely used in Germany.

Show payment methods in order of relevance to your customer

To further customize how payment methods render see Customize payment methods. To add payment methods integrated outside of Stripe, use custom payment methods.

If your integration requires you to list payment methods manually, see Manually list payment methods.

Layout

You can customize the Payment Element’s layout to fit your checkout flow. The following image is the same Payment Element rendered using different layout configurations.

Payment Element with different layouts.

The tabs layout displays payment methods horizontally using tabs. To use this layout, set the value for layout.type to tabs. You can also specify other properties, such as layout.defaultCollapsed.

index.js

View full sample

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

const appearance = { /* appearance */ };
const options = {
 layout: {
 type: 'tabs',
 defaultCollapsed: false,
 }
};

Appearance

Use the Appearance API to control the style of all elements. Choose a theme or update specific details.

For instance, choose the “flat” theme and override the primary text color.

index.js

View full sample

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

const appearance = {
 theme: 'flat',
 variables: { colorPrimaryText: '#262626' }
};

See the Appearance API documentation for a full list of themes and variables.

Options

Stripe elements support more options than these. For instance, display your business name using the business option.

index.js

View full sample

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

const appearance = { /* appearance */};
const options = {
 business: { name: "RocketRides" }
};

The Payment Element supports the following options. See each options’s reference entry for more information.

Errors

Payment Element automatically shows localized customer-facing error messages during client confirmation for the following decline codes:

• card _ declined
• card _ velocity _ exceeded
• expired _ card
• fraudulent
• generic _ decline
• incorrect _ cvc
• incorrect _ number
• incorrect _ zip
• insufficient _ funds
• invalid _ cvc
• invalid _ expiry _ month
• invalid _ expiry _ year
• live _ mode _ test _ card
• lost _ card
• processing _ error
• stolen _ card
• test _ mode _ live _ card

To display messages for other types of errors, refer to error codes and error handling.