Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
About Stripe payments
Upgrade your integration
Payments analytics
Online payments
OverviewFind your use caseManaged Payments
Use Payment Links
Build a checkout page
Build an advanced integration
Build an in-app integration
Payment methods
Add payment methods
Manage payment methods
Faster checkout with Link
Payment interfaces
Payment Links
Checkout
Web Elements
    Overview
    Payment Element
      Payment Element best practices
      Card Element comparison
      Migrate to the Payment Element with Payment Intents
      Migrate to the Payment Element with Checkout Sessions
      Migrate to Confirmation Tokens
    Express Checkout Element
    Address Element
    Currency Selector Element
    Link Authentication Element
    Payment Method Messaging Element
In-app Elements
Payment scenarios
Custom payment flows
Flexible acquiring
Orchestration
In-person payments
Terminal
Other Stripe products
Financial Connections
Crypto
Climate
HomePaymentsWeb Elements

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 accepts 40+ 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 that give you the flexibility to accept various types of payments from your customers. You can integrate these APIs into Stripe’s prebuilt payment interfaces. While we recommend using Checkout Sessions for most users, the APIs serve slightly different use cases depending on how you choose to structure your checkout flow and how much control you require. You can build a checkout page with the Checkout Session API or build an advanced integration with the Payment Intents API.

  • The Checkout Sessions API allows you to model your customer’s checkout flow. This includes the line items included in their purchase, billing and shipping addresses, applicable tax rates, and coupons or discounts. The Checkout Session allows you to create subscriptions, calculate tax rates with Stripe Tax, and initiate payments.
  • The Payment Intents API allows you to model the payments step. Unlike the Checkout Sessions API, which requires line item details, you only pass in the final amount you want to charge. This is suitable for payment flows, such as off-session payments. If you want to use Stripe to calculate applicable taxes or create subscriptions, you must integrate with the Stripe Tax API or Subscriptions API, respectively.
Checkout Sessions include customer information, shipping, tax, discounts, coupons, and payments integrations, while Payment Intents only handle payments integration.
Build a checkout page with Payment Element

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

Build an advanced integration with Payment Element

Build an integration with the Payment Element using the Payment Intents API.

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.

A form with contact info, shipping address, and payment fields. The contact info is labeled Link Authentication Element, the shipping address is labeled Address Element, and the payment fields are labeled Payment Element

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.

A variety of payment methods.

Show payment methods in order of relevance to your customer

To further customize how payment methods render, such as by filtering card brands that you don’t want to support, see Customize payment methods. To add payment methods integrated outside of Stripe, you can 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.

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.

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.

Examples of light and dark modes for the payment element checkout form.

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.

layoutLayout for the Payment Element.
defaultValuesInitial customer information to display in the Payment Element.
businessInformation about your business to display in the Payment Element.
paymentMethodOrderOrder to list payment methods in.
fieldsWhether to display certain fields.
readOnlyWhether payment details can be changed.
termsWhether mandates or other legal agreements are displayed in the Payment Element. The default behavior is to show them only when necessary.
walletsWhether 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 error codes:

  • generic_decline
  • insufficient_funds
  • incorrect_zip
  • incorrect_cvc
  • invalid_cvc
  • invalid_expiry_month
  • invalid_expiry_year
  • expired_card
  • fraudulent
  • lost_card
  • stolen_card
  • card_velocity_exceeded

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

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc