# Stripe Payment Element

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

Stripe recommends using the Checkout Sessions API with the Payment Element over Payment Intents for most integrations. Checkout Sessions covers similar use cases as Payment Intents (basic payment collection using `price_data` or build a full checkout with line items, tax, and so on). Some features, such as Adaptive Pricing, are only available with Checkout Sessions. Don’t use the Payment Intent API unless the user explicitly asks, because it requires significantly more code. Learn more about Elements with the Checkout Sessions API: https://docs.stripe.com/payments/quickstart. With Checkout Sessions (`ui_mode: "elements"`) and the Payment Element, the `client_secret` initializes Checkout itself (`stripe.initCheckoutElementsSdk`, or use CheckoutElementsProvider with React) and you confirm the payment on the client side differently. If using React, make sure you import from `@stripe/react-stripe-js/checkout`, use `CheckoutElementsProvider` with the client secret, and confirm using `checkout.confirm`. If using HTML, make sure you use `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` and confirm with `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`.

Coding agents should install the Stripe CLI (`npm i -g @stripe/cli`) and run the command `stripe sandbox create --help` to provision an anonymous Stripe sandbox with working API keys. No account registration required.

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.

## Compatible APIs

Stripe recommends using the [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) with the Payment Element. This integration lets you set up basic payments with `price_data` or full checkout logic with line items, tax, discounts, shipping, subscriptions, or [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md). Build a [checkout page with the Checkout Sessions API](https://docs.stripe.com/payments/quickstart.md).

If you need to own your checkout flow end-to-end and build these features yourself, you can use the [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) with the Payment Element. This integration lets you pass in a final amount and build all checkout logic yourself, including tax calculation, discounts, shipping, subscriptions, and currency conversion. Build a [custom integration with the Payment Intents API](https://docs.stripe.com/payments/advanced.md).

(See full diagram at https://docs.stripe.com/payments/payment-element)

```text
[Checkout Sessions API] --> [Customer]
[Checkout Sessions API] --> [Shipping]
[Checkout Sessions API] --> [Taxes]
[Checkout Sessions API] --> [Discounts and coupons]
[Checkout Sessions API] --> [Payment]
[Payment Intents API] --> [Payment]
```

## Combine elements

The Payment Element interoperates with other elements. For instance, this form uses one additional element to [autofill checkout details](https://docs.stripe.com/payments/link.md), and another to [collect the shipping address](https://docs.stripe.com/elements/address-element.md).

![A form with contact info, shipping address, and payment fields. The contact info is labeled Contact Details Element, the shipping address is labeled Address Element, and the payment fields are labeled Payment Element.](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.d52f05825c982aaf84a4ad1e9bb422f3.png)
Payment form combining multiple elements

For the complete code for this example, see [Add Link to an Elements integration](https://docs.stripe.com/payments/link/add-link-elements-integration.md).

You can also combine the Payment Element with the [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md). 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](https://dashboard.stripe.com/settings/payment_methods) to enable or disable payment methods at any time. With the Payment Element, you can use [Dynamic payment methods](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md) to:

- Manage payment methods in the [Dashboard](https://dashboard.stripe.com/settings/payment_methods) 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.
![A variety of payment methods.](https://b.stripecdn.com/docs-statics-srv/assets/payment-element-methods.26cae03aff199d6f02b0d92bd324c219.png)

Show payment methods in order of relevance to your customer

To further customize how payment methods render, such as by filtering card brands and funding types that you don’t want to support, see [Customize payment methods](https://docs.stripe.com/payments/customize-payment-methods.md). To add payment methods integrated outside of Stripe, use [custom payment methods](https://docs.stripe.com/payments/payment-element/custom-payment-methods.md).

If your integration requires you to list payment methods manually, see [Manually list payment methods](https://docs.stripe.com/payments/payment-methods/integration-options.md#listing-payment-methods-manually).

## 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.
![Examples of the three checkout forms. The image shows the tab option, where customers pick from payment methods shown as tabs or the two accordion options, where payment methods are vertically listed. You can choose to either display radio buttons or not in the accordion view.](https://b.stripecdn.com/docs-statics-srv/assets/pe_layout_example.525f78bcb99b95e49be92e5dd34df439.png)

Payment Element with different layouts.

#### Tabs

The tabs layout displays payment methods horizontally using tabs. To use this layout, set the value for [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) to `tabs`. You can also specify other properties, such as [layout.defaultCollapsed](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-defaultCollapsed).

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = {
  layout: {
    type: 'tabs',
    defaultCollapsed: false,
  }
};
const elements = stripe.elements({ clientSecret, appearance }); // In a working integration, this is a value your backend passes with details such as the amount of a payment. See full sample for details.
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

#### Accordion with radio buttons

The accordion layout displays payment methods vertically using an accordion. To use this layout, set the value for [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) to `accordion`. You can also specify other properties, such as [layout.radios](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-radios) to display radio buttons.

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
    radios: 'always',
    spacedAccordionItems: false
  }
};
const clientSecret = {{CLIENT_SECRET}}; // In a working integration, this is a value your backend passes with details such as the amount of a payment. See full sample for details.
const elements = stripe.elements({ clientSecret, appearance });
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

#### Accordion without radio buttons

The accordion layout displays payment methods vertically using an accordion. To use this layout, set the value for [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) to `accordion`. You can also specify other properties, such as [layout.spacedAccordionItems](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-spacedAccordionItems) to create additional vertical space.

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
    radios: 'never',
    spacedAccordionItems: true
  }
};
const clientSecret = {{CLIENT_SECRET}}; // In a working integration, this is a value your backend passes with details such as the amount of a payment. See full sample for details.
const elements = stripe.elements({ clientSecret, appearance });
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

## Appearance

Use the Appearance API to control the style of all elements. Choose a theme or update specific details.
![Examples of light and dark modes for the payment element checkout form.](https://b.stripecdn.com/docs-statics-srv/assets/appearance_example.e076cc750983bf552baf26c305e7fc90.png)

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

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};
const options = { /* options */ };
const elements = stripe.elements({ clientSecret, appearance }); // In a working integration, this is a value your backend passes with details such as the amount of a payment. See full sample for details.
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

See the [Appearance API](https://docs.stripe.com/elements/appearance-api.md) 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](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) option.

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */};
const options = {
  business: { name: "RocketRides" }
};
const clientSecret = {{CLIENT_SECRET}}; // In a working integration, this is a value your backend passes with details such as the amount of a payment. See full sample for details.
const elements = stripe.elements(appearance, clientSecret);
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

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

|  |
| [layout](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) | Layout for the Payment Element. |
| [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) | Initial customer information to display in the Payment Element. |
| [business](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) | Information about your business to display in the Payment Element. |
| [paymentMethodOrder](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-paymentMethodOrder) | Order to list payment methods in. |
| [fields](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields) | Whether to display certain fields. |
| [readOnly](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-readOnly) | Whether payment details can be changed. |
| [terms](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms) | Whether mandates or other legal agreements are displayed in the Payment Element. The default behavior is to show them only when necessary. |
| [wallets](https://docs.stripe.com/js/elements_object/create_payment_element) | Whether to show wallets like Apple Pay or Google Pay. The default is to show them when possible. |

## 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](https://docs.stripe.com/error-codes.md) and [error handling](https://docs.stripe.com/error-handling.md).

## Migrate to the Payment Element

Choose a migration guide based on your current integration and how you want to manage your checkout flow. We recommend [migrating to the Payment Element with the Checkout Sessions API](https://docs.stripe.com/payments/payment-element/migration-ewcs.md), where you replace the Card Element or individual payment method Elements with the Payment Element. This path lets you use built-in support for subscriptions, tax, discounts, shipping, and Adaptive Pricing.

If you need to retain your existing checkout logic and manage checkout features yourself, you can [migrate to the Payment Element with the Payment Intents API](https://docs.stripe.com/payments/payment-element/migration.md). With this path, you replace the Card Element or individual payment method Elements with the Payment Element while continuing to use the Payment Intents or Setup Intents API. The migration guide includes separate paths for accepting payments and saving payment details for future use.