PaymentElement Use the PaymentElement from @stripe/react-stripe-js to collect payment details for more than 40 payment methods from around the globe. The component must be rendered inside an Elements Provider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating the Payment Element. - layout Specify the layout for the Payment Element. If you only pass a layout type ('accordion' or ‘tabs’) without any additional parameters, the Payment Element renders using that layout and the default values associated with it. An object can also be passed to specify the layout with additional configuration. - type Defines the layout to render the Payment Element. - defaultCollapsed Controls if the Payment Element renders in a collapsed state (where no payment method is selected by default). When you leave this undefined, Stripe renders the experience that it determines will have the best conversion. - radios Controls when to render each Payment Method with a radio input next to its logo. The radios visually indicate the current selection of the Payment Element. Defaults to 'auto'. - 'always' — Always show radio inputs. - 'never' — Never show radio inputs. - 'if_multiple' — Show radio inputs only when there are multiple payment methods available. When there is only one payment method, no radio input is displayed. - 'auto' — Stripe determines the best experience to optimize conversion. This property is only applicable to the accordion layout. - spacedAccordionItems When true, the Payment Methods render as standalone buttons with space in between them. This property is only applicable to the accordion layout. - visibleAccordionItemsCount Sets the max number of Payment Methods visible before using the "More" button to hide additional Payment Methods. Set this value to 0 to disable the "More" button and render all available Payment Methods. Default is 5. This property is only applicable to the accordion layout. - paymentMethodLogoPosition Sets the position of the payment method logo in each accordion item. Default is start. This property is only applicable to the accordion layout. - defaultValues Provide initial customer information that will be displayed in the Payment Element. The form will render with empty fields if not provided. - billingDetails Specify customer's billing details, which lets you pre-fill a customer’s name, email, phone number and address if required by payment method. Pre-filling as much information as possible streamlines the checkout process. - name - email - phone - address - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - postal_code The postal code or ZIP code, also known as PIN code in India. - paymentMethods Specify customer's default information for different payment methods. Pre-filling as much information as possible streamlines the checkout process. - ideal - bank A pre-filled iDEAL bank value for the Payment Element. Can only be one of the banks listed in the iDEAL guide (e.g., abn_amro). - payto - usePayId When true, the PayTo payment method will default to showing the PayID input instead of BSB/account number fields. Customers can still switch between PayID and BSB/account number using the toggle link. - card Specify default settings for card payments. - network Specifies a network preference for Card Brand Choice. The first network in the array that matches a network on the entered co-branded card will be selected by default in the Card Brand Choice dropdown. See the supported networks for valid values. - business Provide information about your business that will be displayed in the Payment Element. This information will be retrieved from your Stripe account if not provided. - name The name of your business. Your business name will be used to render mandate text for some payment methods. - paymentMethodOrder By default, the Payment Element will use a dynamic ordering that optimizes payment method display for each user. You can override the default order in which payment methods are displayed in the Payment Element with a list of payment method types. If the associated PaymentIntent has payment method types not specified in paymentMethodOrder, they will be displayed after the payment methods you specify. If you specify payment method types not on the associated PaymentIntent, they will be ignored. - fields By default, the Payment Element collects all necessary details to complete a payment. For some payment methods, the Payment Element collects details such as name or email that you might have already collected from the customer. If this is the case, you can prevent the Payment Element from collecting these details by using the fields option. If you disable collecting certain fields with the fields option, you must pass that same data to stripe.confirmPayment or we'll reject the payment. You can set billingDetails at the top level to apply the same field collection settings to all payment methods, or set billingDetails under a supported payment method type to override the top-level setting for that payment method. Learn how to customize the billing details to collect and the customized fields. - billingDetails Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto. - name Specify always to require the Payment Element to collect the customer's billing name. - email Specify never to avoid collecting email in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.email=never and walletOptions.emailRequired=true, email is still collected from wallets. - phone Specify never to avoid collecting phone in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.phone=never and walletOptions.phoneNumberRequired=true, phone is still collected from wallets. - address Specify if_required to only collect the minimum billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. Unlike the never option, you don't need to include fields omitted in the Payment Element when confirming the payment. This can reduce the amount of information required to complete the form. Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - postalCode The postal code or ZIP code, also known as PIN code in India. - [paymentMethodType] Optionally specify the billing detail collection settings for any Payment Element payment method type. Examples of valid values are card, klarna, or us_bank_account. You can include one or more payment method type keys. - billingDetails Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto. - name Specify always to require the Payment Element to collect the customer's billing name. - email Specify never to avoid collecting email in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.email=never and walletOptions.emailRequired=true, email is still collected from wallets. - phone Specify never to avoid collecting phone in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.phone=never and walletOptions.phoneNumberRequired=true, phone is still collected from wallets. - address Specify if_required to only collect the minimum billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. Unlike the never option, you don't need to include fields omitted in the Payment Element when confirming the payment. This can reduce the amount of information required to complete the form. Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - postalCode The postal code or ZIP code, also known as PIN code in India. - readOnly Applies a read-only state to the Payment Element so that payment details can’t be changed. Default is false. Enabling the readOnly option doesn't change the Payment Element's visual appearance. If you want to adjust the way the Payment Element looks, use the Appearance API. - terms Control how mandates or other legal agreements are displayed in the Payment Element. Use never to never display legal agreements. The default setting is auto, which causes legal agreements to only be shown when necessary. Consult your legal and compliance advisors before making any changes to the text of mandates or legal agreements. You can't use the terms option to violate obligations under your Stripe agreement, Stripe policies, applicable laws or scheme rules. - applePay - auBecsDebit - bancontact - card - cashapp - googlePay - ideal - paypal - sepaDebit - sofort - usBankAccount - wallets By default, the Payment Element will display all the payment methods that the underlying Payment Intent was created with. However, wallets like Apple Pay and Google Pay are not payment methods per the Payment Intent API. They will show when the Payment Intent has the card payment method and the customer is using a supported platform and have an active card in their account. This is the auto behavior, and it is the default for choice for all wallets. If you do not want to show a given wallet as a payment option, you can set its property in wallets to never. - applePay - googlePay - link - walletOptions Options to control the information collected from the customer when paying with a wallet payment method. - emailRequired Collect the customer's email from wallet payment methods by setting this option to true. - phoneNumberRequired Collect the customer's phone number from wallet payment methods by setting this option to true. PayPal doesn't provide a phone number, even when this option is set to true. Google Pay makes a best effort to return the phone number registered to the wallet, but doesn't guarantee it will be provided in all cases. Link makes a best effort to return the phone number registered to the wallet, but doesn't guarantee it will be provided in all cases. - applePay Specify Apple Pay specific options. These are passed through to the Apple Pay API. - recurringPaymentRequest Specify a request to set up a recurring payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - regularBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - trialBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - billingAgreement - deferredPaymentRequest Specify a request to set up a deferred payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - deferredBilling - amount - amountType Indicates whether the billing amount is known at request time. When set to 'final', the Apple Pay payment sheet shows the configured amount. - label - deferredPaymentDate - billingAgreement - freeCancellationDate If set, you must also supply a freeCancellationDateTimeZone., - freeCancellationDateTimeZone "If set, you must also supply a freeCancellationDate., - automaticReloadPaymentRequest Specify a request to set up an automatic reload payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - automaticReloadBilling - amount - label - automaticReloadPaymentThresholdAmount - billingAgreement - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render PaymentElement
