## React Stripe.js reference The React bindings for Stripe.js provide context providers, hooks, and Element components for both [Checkout Sessions](/api/checkout/sessions.md) and direct [PaymentIntent](/api/payment_intents.md) or [SetupIntent](/api/setup_intents.md) integrations. The sections below document the APIs exported from `@stripe/react-stripe-js` and `@stripe/react-stripe-js/checkout`, grouped by the provider you render (`CheckoutProvider` or `Elements`). ## Using the Checkout provider Build your Stripe integration using React, Stripe Elements, and the [Checkout Sessions API](/api/checkout/sessions.md). See [build a checkout page](/docs/payments/quickstart-checkout-sessions.md) for steps on using Elements with the Checkout Sessions API. The following React components and hooks are available to use as part of your integration. ## CheckoutProvider The `CheckoutProvider` component allows you to use Element components and access data from your [Checkout Session](/api/checkout/sessions/object.md) in any nested component. Wrap the portion of your React tree that renders individual Element components to make the Checkout instance available via React context. To use `CheckoutProvider`, call `loadStripe` from `@stripe/stripe-js` with your publishable key. The `loadStripe` function asynchronously loads the Stripe.js script and initializes a Stripe object. Pass the returned `Promise` to `CheckoutProvider` along with the [client secret](/api/checkout/sessions/object.md#checkout_session_object-client_secret) of your Checkout Session. ### Props - `stripe` (`Stripe` or `Promise`) **required** A [Stripe object](/js/initializing.md) or a `Promise` resolving to a Stripe object. The easiest way to initialize a Stripe object is with the [Stripe.js wrapper module](https://github.com/stripe/stripe-js/blob/master/README.md#readme). After this prop has been set, it can not be changed. - `options` (object) **required** Options for `CheckoutProvider`. - `clientSecret` (Promise | string) **required** The Checkout Session [client secret](/api/checkout/sessions/object.md#checkout_session_object-client_secret) or a promise that resolves to the client secret. - `elementsOptions` (object) A set of options to configure Elements created with [Checkout Sessions](/api/checkout/sessions.md). - `appearance` (object) Match the design of your site with the [appearance option](/elements/appearance-api.md). The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more. - `loader` ('auto' | 'always' | 'never') Display skeleton loader UI while waiting for Elements to fully load after they're mounted. Default is `'auto'` (Stripe determines whether or not to show a loader UI). - `fonts` (array) An array of custom fonts that elements created from the `Elements` object can use. You can specify fonts as [CssFontSource](#css_font_source_object) or [CustomFontSource](#custom_font_source_object) objects. - `savedPaymentMethod` (object) Options to configure what Elements displays when used to [Save payment details during payment](/payments/checkout/save-during-payment.md). - `enableRedisplay` ('auto' | 'never') Toggle if Elements redisplays Customer saved Payment Methods. Default is `'auto'`. Prior to Clover, this defaulted to `'never'`. - `enableSave` ('auto' | 'never') Toggle if the Payment Element collects consent to save a Customer's Payment Methods. Default is `'auto'`. Prior to Clover, this defaulted to `'never'`. - `syncAddressCheckbox` ('billing' | 'shipping' | 'none') Used with the [Address Element](/elements/address-element.md). The `syncAddressCheckbox` parameter configures which Address Element to show the checkbox. The checkbox allows the customer the option to sync billing and shipping addresses when both Billing and Shipping Address Elements are used in a single Elements instance. - `adaptivePricing` (object) Options for [Adaptive Pricing](/payments/currencies/localize-prices/adaptive-pricing.md?payment-ui=embedded-components). - `allowed` (boolean) Whether Adaptive Pricing can be used with this integration. Default is `false`. [Additional setup](/payments/currencies/localize-prices/adaptive-pricing.md?payment-ui=embedded-components) is required before you can use Adaptive Pricing with embedded components. ### Mount CheckoutProvider ```jsx import React from 'react'; import {CheckoutProvider} from '@stripe/react-stripe-js/checkout'; import {loadStripe} from '@stripe/stripe-js'; import {useMemo} from 'react'; // Make sure to call `loadStripe` outside of a component's render to avoid // recreating the `Stripe` object on every render. const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); const App = () => { const promise = useMemo(() => { return fetch('/create-checkout-session', { method: 'POST', }) .then((res) => res.json()) .then((data) => data.clientSecret); }, []); return ( ); } export default App; ``` ## useCheckout The `useCheckout` hook returns a disjoint union describing the loading state: * `{type: "loading"}` * `{type: "error", error: { message: string }}` * `{type: "success", checkout: object }`. Upon success, it returns a [Session object](/js/custom_checkout/session_object.md) as well as actions to update the Checkout Session. ### Object properties - `id` (string) The ID of the Checkout Session. - `billingAddress` (nullable object) Billing details of the Customer. - `name` (nullable string) Full name. - `address` (nullable object) Address. - `country` (string) Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). - `line1` (nullable string) Address line 1 (e.g., street, PO Box, or company name). - `line2` (nullable string) Address line 2 (e.g., apartment, suite, unit, or building). - `city` (nullable string) City, district, suburb, town, or village. - `postal_code` (nullable string) ZIP or postal code. - `state` (nullable string) State, county, province, or region. - `businessName` (nullable string) The business name as configured in the Business Public Details settings of your Stripe account. - `canConfirm` (boolean) Whether the Checkout Session has collected enough data to confirm. Use this field to indicate to your customer if they can proceed, such as disabling the pay button. - `currency` (enum) Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](/currencies.md). - `currencyOptions` (nullable array of objects) The currency options available on the Checkout Session when using [Adaptive Pricing](/checkout/custom-checkout/adaptive-pricing.md). - `amount` (string) A formatted string representing the total amount in the source currency, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the total amount in the source currency in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `currency` (enum) Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. - `currencyConversion` (optional object) Currency conversion details. This is only present for the customer currency. - `fxRate` (decimal string) The exchange rate used to convert source currency amounts to customer currency amounts. - `sourceCurrency` (enum) The creation currency of the Checkout Session before localization. - `discountAmounts` (array of objects) The aggregate amounts calculated per discount for all line items. - `amount` (string) A formatted string representing the discount amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `displayName` (string) A user-facing description of the discount. - `promotionCode` (nullable string) The customer-facing promotion code that was used to apply this discount, if any. - `recurring` (nullable object) Details of how the discount applies to recurring payments. - `type` (enum) One of `forever` or `repeating`. * `forever`: Applies to all charges from a subscription with this coupon applied. * `repeating`: Applies to charges in the first `durationInMonths` months from a subscription with this coupon applied. - `durationInMonths` (nullable integer) If `duration` is `repeating`, the number of months the coupon applies. Null otherwise. - `percentOff` (nullable integer) An integer representing the discount amount as a percentage. - `email` (nullable string) The Customer's email address. - `lastPaymentError` (nullable object) The error encountered the last time the Checkout Session was confirmed. - `message` (string) An error message to be displayed to the customer. - `lineItems` (array of objects) A list of items the customer is purchasing. - `id` (string) Unique identifier for the object. - `subtotal` (nullable object) Total before any discounts or exclusive taxes are applied. - `amount` (string) A formatted string representing the subtotal amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the subtotal amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `discount` (nullable object) Total discount amount. A positive number reduces the amount to be paid. - `amount` (string) A formatted string representing the discount amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `taxExclusive` (nullable object) Total amount of exclusive tax (tax that is collected in addition to the subtotal). - `amount` (string) A formatted string representing the exclusive tax amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the exclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `taxInclusive` (nullable object) Total amount of inclusive tax (tax that is already included in the subtotal). - `amount` (string) A formatted string representing the inclusive tax amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the inclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `total` (nullable object) Total amount for this line item, including discounts and tax. - `amount` (string) A formatted string representing the total amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the total amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `unitAmount` (nullable object) The amount representing the cost of a single unit of the item. - `amount` (string) A formatted string representing the unit amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the unit amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `description` (optional string) An arbitrary string attached to the object. Often useful for displaying to users. - `name` (string) The item's name, meant to be displayable to users. - `images` (array of strings) An array of image URLs for the line item. Specify [images](/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product_data-images) on the Product when creating the Checkout Session. - `quantity` (integer) The quantity of products being purchased. - `discountAmounts` (array of objects) The amount of discount calculated per discount for this line item. - `amount` (string) A formatted string representing the discount amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `displayName` (string) A user-facing description of the discount. - `promotionCode` (nullable string) The customer-facing promotion code that was used to apply this discount, if any. - `recurring` (nullable object) Details of how the discount applies to recurring payments. - `type` (enum) One of `forever` or `repeating`. * `forever`: Applies to all charges from a subscription with this coupon applied. * `repeating`: Applies to charges in the first `durationInMonths` months from a subscription with this coupon applied. - `durationInMonths` (nullable integer) If `duration` is `repeating`, the number of months the coupon applies. Null otherwise. - `percentOff` (nullable integer) An integer representing the discount amount as a percentage. - `taxAmounts` (nullable array of objects) The amount of tax calculated per tax rate for this line item. - `amount` (string) A formatted string representing the tax amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `inclusive` (boolean) Whether this tax amount is [inclusive or exclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax). - `displayName` (string) A user-facing description of the tax. - `recurring` (nullable object) The recurring components of a price such as `interval` and `intervalCount`. - `interval` (enum) Specifies billing frequency. Either `day`, `week`, `month`, or `year`. - `intervalCount` (integer) The number of intervals between subscription billings. For example, `interval=month` and `intervalCount=3` bills every 3 months. - `usageType` (enum) One of `licensed` or `metered`. `licensed` automatically bills the quantity set when adding it to a subscription. `metered` aggregates the total usage based on usage records. - `isProrated` (boolean) When true, the amount to be collected today is a prorated amount for a partial billing period, such as when using [billing_cycle_anchor](/api/checkout/sessions/create.md#create_checkout_session-subscription_data-billing_cycle_anchor). - `adjustableQuantity` (nullable object) Configuration for this item's quantity to be adjusted by the customer during checkout. - `maximum` (integer) The maximum quantity the customer can purchase for the Checkout Session. - `minimum` (integer) The minimum quantity the customer can purchase for the Checkout Session. - `livemode` (boolean) Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode. - `minorUnitsAmountDivisor` (integer) The factor used to convert between minor and major currency units. This value represents the number of minor currency units per one major unit. For example, in USD, where cents are the minor unit, the divisor is 100. In JPY, which has no minor units, the divisor is 1. - `phoneNumber` (nullable string) The Customer's phone number. - `recurring` (object) Details about recurring payments set up by the Checkout Session. - `interval` (enum) Specifies billing frequency. Either `day`, `week`, `month`, or `year`. - `intervalCount` (integer) The number of intervals between subscription billings. For example, `interval=month` and `intervalCount=3` bills every 3 months. - `dueNext` (object) Details about the next scheduled recurring payment. - `subtotal` (nullable object) Total before any discounts or exclusive taxes are applied. - `amount` (string) A formatted string representing the subtotal amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the subtotal amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `discount` (nullable object) Total discount amount. A positive number reduces the amount to be paid. - `amount` (string) A formatted string representing the discount amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `taxExclusive` (nullable object) Total amount of exclusive tax (tax that is collected in addition to the subtotal). - `amount` (string) A formatted string representing the exclusive tax amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the exclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `taxInclusive` (nullable object) Total amount of inclusive tax (tax that is already included in the subtotal). - `amount` (string) A formatted string representing the inclusive tax amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the inclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `billingCycleAnchor` (nullable integer) A future Unix timestamp to anchor the subscription's billing cycle. The anchor is the reference point that aligns future billing cycle dates. If not present, the subscription starts immediately. - `trial` (nullable object) Details about a free trial, if there is one. - `trialEnd` (integer) Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. - `trialPeriodDays` (integer) Integer representing the number of trial period days before the customer is charged for the first time. - `savedPaymentMethods` (array of objects) An array of payment methods attached to the Customer. - `id` (string) ID of the PaymentMethod object - `type` (enum) The [type](/api/payment_methods/object.md#payment_method_object-type) of the PaymentMethod - `billingDetails` (object) Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods. - `email` (nullable string) Email address. - `phone` (nullable string) Billing phone number (including extension). - `name` (nullable string) Full name. - `address` (nullable object) Address. - `country` (string) Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). - `line1` (nullable string) Address line 1 (e.g., street, PO Box, or company name). - `line2` (nullable string) Address line 2 (e.g., apartment, suite, unit, or building). - `city` (nullable string) City, district, suburb, town, or village. - `postal_code` (nullable string) ZIP or postal code. - `state` (nullable string) State, county, province, or region. - `card` (object) If this is a `card` PaymentMethod, this hash contains the user's card details. - `brand` (string) The brand to use when displaying the card, this accounts for customer's brand choice on dual-branded cards. Can be american_express, cartes_bancaires, diners_club, discover, eftpos_australia, interac, jcb, mastercard, union_pay, visa, or other and may contain more values in the future. - `expMonth` (integer) Two-digit number representing the card's expiration month. - `expYear` (integer) Four-digit number representing the card's expiration year. - `last4` (string) The last four digits of the card. - `shipping` (nullable object) The selected shipping option, if any. - `shippingOption` (object) Details of the selected shipping option. - `id` (string) Unique identifier for the object. - `amount` (string) A formatted string representing the shipping amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the shipping amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `currency` (string) Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. - `displayName` (nullable string) A user-facing description of the shipping option. - `deliveryEstimate` (nullable object) The estimated range for how long shipping will take. - `maximum` (nullable object) The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - `unit` (string) A unit of time. Either `business_day`, `day`, `hour`, `week`, or `month`. - `value` (integer) Must be greater than 0. - `minimum` (nullable object) The lower bound of the estimated range. If empty, represents no lower bound. - `unit` (string) A unit of time. Either `business_day`, `day`, `hour`, `week`, or `month`. - `value` (integer) Must be greater than 0. - `taxAmounts` (array of objects) The amount of tax calculated per tax rate for shipping costs. - `amount` (string) A formatted string representing the tax amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `inclusive` (boolean) Whether this tax amount is [inclusive or exclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax). - `displayName` (string) A user-facing description of the tax. - `shippingAddress` (nullable object) Shipping address of the Customer. - `name` (nullable string) Full name. - `address` (nullable object) Address. - `country` (string) Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). - `line1` (string) Address line 1 (e.g., street, PO Box, or company name). - `line2` (nullable string) Address line 2 (e.g., apartment, suite, unit, or building). - `city` (nullable string) City, district, suburb, town, or village. - `postal_code` (nullable string) ZIP or postal code. - `state` (nullable string) State, county, province, or region. - `shippingOptions` (array of objects) The list of shipping options that can be selected. - `id` (string) Unique identifier for the object. - `amount` (string) A formatted string representing the shipping amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the shipping amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `currency` (string) Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. - `displayName` (nullable string) A user-facing description of the shipping option. - `deliveryEstimate` (nullable object) The estimated range for how long shipping will take. - `maximum` (nullable object) The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - `unit` (string) A unit of time. Either `business_day`, `day`, `hour`, `week`, or `month`. - `value` (integer) Must be greater than 0. - `minimum` (nullable object) The lower bound of the estimated range. If empty, represents no lower bound. - `unit` (string) A unit of time. Either `business_day`, `day`, `hour`, `week`, or `month`. - `value` (integer) Must be greater than 0. - `status` (object) Status of the Checkout Session. - `type` (enum) One of `open`, `expired`, or `complete`. * `open`: The Checkout Session is still in progress. * `expired`: The Checkout Session has expired. No further processing will occur. * `complete`: The Checkout Session is complete. Payment processing may still be in progress. - `paymentStatus` (nullable enum) One of `paid`, `unpaid`, or `no_payment_required`. Only present when `type=complete`. * `paid`: The payment funds are available in your account. * `unpaid`: The payment funds are not yet available in your account. * `no_payment_required`: The payment is delayed to a future date, or the Checkout Session is in setup mode and doesn't require a payment at this time. - `tax` (object) Details about the tax computation status. - `status` (enum) One of `ready`, `requires_shipping_address`, or `requires_billing_address`. * `ready`: The final tax amount is computed, and the session is ready for confirmation. * `requires_shipping_address`: A shipping address must be provided to calculate tax. * `requires_billing_address`: A billing address must be provided to calculate tax. - `taxAmounts` (nullable array of objects) The aggregate amounts calculated per tax rate for all line items. This value is `null` if tax has not yet been computed, i.e. the Customer's address has not been collected yet. - `amount` (string) A formatted string representing the tax amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `inclusive` (boolean) Whether this tax amount is [inclusive or exclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax). - `displayName` (string) A user-facing description of the tax. - `total` (object) Tax and discount details for the computed total amount. Use this field to render an amount breakdown to your customer, such as in an order summary. - `subtotal` (object) The total amount of line items, excluding tax, discounts, and shipping. - `amount` (string) A formatted string representing the subtotal amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the subtotal amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `taxExclusive` (object) The sum of all [exclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax) tax amounts - `amount` (string) A formatted string representing the exclusive tax amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the exclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `taxInclusive` (object) The sum of all [inclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax) tax amounts - `amount` (string) A formatted string representing the inclusive tax amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the inclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `shippingRate` (object) The sum of all shipping amounts. - `amount` (string) A formatted string representing the total shipping amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the total shipping amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `discount` (object) The sum of all the discounts. A positive number reduces the amount to be paid. - `amount` (string) A formatted string representing the discount amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `total` (object) Total computed amount, including discounts and tax. - `amount` (string) A formatted string representing the total amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the total amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `appliedBalance` (object) Total amount of [customer credit balance](/billing/customer/balance.md) to be applied to the payment. A positive number increases the amount to be paid, and a negative number decreases the amount to be paid. - `amount` (string) A formatted string representing the applied customer balance amount, including currency symbols. - `minorUnitsAmount` (integer) An integer representing the applied customer balance amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - `balanceAppliedToNextInvoice` (boolean) When true, no payment will be collected immediately. Instead, the amount due will be added to the Customer's next invoice. This can happen when the amount due today is less than the [minimum chargeable amount](/currencies.md#minimum-and-maximum-charge-amounts). ### Call useCheckout hook ```jsx import React from 'react'; import {useCheckout} from '@stripe/react-stripe-js/checkout'; const CheckoutPage = () => { const checkoutState = useCheckout(); if (checkoutState.type === "loading") { // ... your loading component here } if (checkoutState.type === "error") { // ... your error component here } const {currency, currencyOptions, lineItems, taxAmounts, total, recurring} = checkoutState.checkout; // ... your component here } export default CheckoutPage; ``` ## Apply a promotion code Use this method to apply a promotion code that your customer enters. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `promotionCode` (string) **required** The promotion code to apply to the Checkout Session. ### Apply a promotion code ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {applyPromotionCode} = checkoutState.checkout; applyPromotionCode('PROMOTION_CODE'); } ``` ## Remove a promotion code Use this method to remove the currently applied promotion code, if applicable. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. ### Remove a promotion code ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {removePromotionCode} = checkoutState.checkout; removePromotionCode(); } ``` ## Update the Customer's shipping address Use this method to update the Customer's shipping address. If your integration uses the [Express Checkout Element](/elements/express-checkout-element.md), the shipping address is collected directly from the wallet and the value set by `updateShippingAddress` is not used for express checkout payments. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `shippingAddress` (nullable object) **required** New shipping address for the Customer. - `name` (optional string) Full name. - `address` (optional object) Address. - `country` (string) **required** Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). - `line1` (string) **required** Address line 1 (e.g., street, PO Box, or company name). - `line2` (optional string) Address line 2 (e.g., apartment, suite, unit, or building). - `city` (optional string) City, district, suburb, town, or village. - `postal_code` (optional string) ZIP or postal code. - `state` (optional string) State, county, province, or region. ### Update the Customer's shipping address ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {updateShippingAddress} = checkoutState.checkout; updateShippingAddress({ address: { line1: '27 Fredrick Ave', city: 'Brothers', state: 'OR', postal_code: '97712', country: 'US', } }); } ``` ## Update the Customer's billing address Use this method to update the Customer's billing address. If your integration uses the [Express Checkout Element](/elements/express-checkout-element.md), the billing address is collected directly from the wallet and the value set by `updateBillingAddress` is not used for express checkout payments. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `billingAddress` (nullable object) **required** New billing information for the Customer. - `name` (optional string) Full name. - `address` (optional object) Address. - `country` (string) **required** Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). - `line1` (optional string) Address line 1 (e.g., street, PO Box, or company name). - `line2` (optional string) Address line 2 (e.g., apartment, suite, unit, or building). - `city` (optional string) City, district, suburb, town, or village. - `postal_code` (optional string) ZIP or postal code. - `state` (optional string) State, county, province, or region. ### Update the Customer's billing address ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {updateBillingAddress} = checkoutState.checkout; updateBillingAddress({ address: { line1: '27 Fredrick Ave', city: 'Brothers', state: 'OR', postal_code: '97712', country: 'US', } }); } ``` ## Update the Customer's email address Use this method to update the Customer's email address. If your integration uses [Link](/payments/link.md) and you do not provide an email during Checkout Session creation, you must call `updateEmail` for Link to appear as a payment option for returning users. If your integration uses the [Express Checkout Element](/elements/express-checkout-element.md), the email address is collected directly from the wallet and the value set by `updateEmail` is not used for express checkout payments. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `email` (nullable string) **required** The Customer's email address. ### Update the Customer's email address ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {updateEmail} = checkoutState.checkout; updateEmail('jenny.rosen@example.com'); } ``` ## Update the Customer's phone number Use this method to update the Customer's phone number. If your integration uses the [Express Checkout Element](/elements/express-checkout-element.md), the phone number is collected directly from the wallet and the value set by `updatePhoneNumber` is not used for express checkout payments. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `phoneNumber` (nullable string) **required** The Customer's phone number. ### Update the Customer's phone number ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {updatePhoneNumber} = checkoutState.checkout; updatePhoneNumber('5554242424'); } ``` ## Update the Customer's business name and tax ID Use this method to update the Customer's business name and tax ID. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `taxIdInfo` The Customer's tax ID information including the business name and tax ID. - `businessName` (nullable string) **required** The Customer's business name. - `taxId` **required** The Customer's tax ID. - `type` **required** One of [the supported tax ID types](/tax/checkout/tax-ids?payment-ui=embedded-components.md#supported-types) - `value` (nullable string) **required** The value of the tax ID. ### Update the Customer's business name and tax ID ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {updateTaxIdInfo} = checkoutState.checkout; updateTaxIdInfo({ businessName: 'Acme, Inc.', taxID: { type: 'eu_vat', value: 'DK12345678' } }); } ``` ## Update line item quantities Use this method to change the quantity of a line item. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `options` (object) **required** Options for `updateLineItemQuantity`. - `lineItem` (string) **required** The [ID](/js/custom_checkout/session_object.md#custom_checkout_session_object-lineItems-id) of the line item to update. - `quantity` (integer) **required** The new quantity of the line item. ### Update line item quantities ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {updateLineItemQuantity} = checkoutState.checkout; updateLineItemQuantity({ lineItem: 'LINE_ITEM_ID', quantity: 2, }); } ``` ## Update the selected shipping option Use this method to update the selected shipping option. See [shippingOptions](/js/custom_checkout/session_object.md#custom_checkout_session_object-shippingOptions) for a list of the available shipping options. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `shippingOption` (string) The [ID](/js/custom_checkout/session_object.md#custom_checkout_session_object-shippingOptions-id) of the shipping option to select. ### Update the selected shipping option ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {updateShippingOption} = checkoutState.checkout; updateShippingOption('SHIPPING_OPTION_ID'); } ``` ## Confirm the Checkout Session Use this method to confirm the Checkout Session. You must either read [total.total.amount](/js/custom_checkout/session_object.md#custom_checkout_session_object-total-total-amount) or each of [total.total.minorUnitsAmount](/js/custom_checkout/session_object.md#custom_checkout_session_object-total-total-minorUnitsAmount) and [currency](/js/custom_checkout/session_object.md#custom_checkout_session_object-currency) and [minorUnitsAmountDivisor](/js/custom_checkout/session_object.md#custom_checkout_session_object-minorUnitsAmountDivisor) from the checkout object and display in your UI, otherwise an error will be thrown. This helps keep your checkout page in sync as the Checkout Session updates, including adding future Stripe features, with minimal UI code changes. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `options` (object) Options for `confirm`. - `returnUrl` (string) The URL to redirect your customer to after they authenticate or cancel their payment on the payment method’s app or site. This parameter is only required if you didn't specify the `return_url` when creating the Checkout Session. - `paymentMethod` (string) The ID of a previously collected [PaymentMethod](/api/payment_methods/object.md) to use for confirmation. When this option is provided, Custom Checkout will ignore the payment method collected by the PaymentElement and attempt confirmation using the provided PaymentMethod. - `savePaymentMethod` (boolean) Whether your Customer has provided consent to save the payment method for future purchases. Learn how to [save payment methods](/checkout/custom-checkout/save-payment-methods-checkout.md). - `redirect` ('always' | 'if_required') By default, `confirm` will always redirect to your `returnUrl` after a successful confirmation. If you set `redirect: "if_required"`, then `confirm` will only redirect if your user chooses a redirect-based payment method. - `email` (string) The Customer's email address. If provided, this value overrides any values previously set using [updateEmail](/js/custom_checkout/update_email.md). - `phoneNumber` (string) The Customer's phone number. If provided, this value overrides any values previously set using [updatePhoneNumber](/js/custom_checkout/update_phone_number.md). - `billingAddress` (object) The Customer's billing address. If provided, this value overrides any values previously set using [updateBillingAddress](/js/custom_checkout/update_billing_address.md). - `name` (optional string) Full name. - `address` (optional object) Address. - `country` (string) **required** Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). - `line1` (optional string) Address line 1 (e.g., street, PO Box, or company name). - `line2` (optional string) Address line 2 (e.g., apartment, suite, unit, or building). - `city` (optional string) City, district, suburb, town, or village. - `postal_code` (optional string) ZIP or postal code. - `state` (optional string) State, county, province, or region. - `shippingAddress` (object) The Customer's shipping address. If provided, this value overrides any values previously set using [updateShippingAddress](/js/custom_checkout/update_shipping_address.md). - `name` (optional string) Full name. - `address` (optional object) Address. - `country` (string) **required** Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). - `line1` (string) **required** Address line 1 (e.g., street, PO Box, or company name). - `line2` (optional string) Address line 2 (e.g., apartment, suite, unit, or building). - `city` (optional string) City, district, suburb, town, or village. - `postal_code` (optional string) ZIP or postal code. - `state` (optional string) State, county, province, or region. - `expressCheckoutConfirmEvent` (object) The [event object](/js/elements_object/express_checkout_element_confirm_event.md#express_checkout_element_on_confirm-handler) passed to your Express Checkout Element `confirm` handler. ### Confirm the Checkout Session ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {confirm} = checkoutState.checkout; confirm({ returnUrl: 'RETURN_URL', }); } ``` ## Run server update Use this method to wrap an async function that makes a request to your server to update the Checkout Session. > `runServerUpdate` enforces a 20-second timeout for your update function. If your function doesn't resolve within 20 seconds, `runServerUpdate` returns an error. Wrap `runServerUpdate` calls in `try`/`catch` blocks to handle any errors. This method returns a `Promise` that resolves with an object containing the following fields: * `type`: one of either `"success"` or `"error"` * `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state. * `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer. - `userFunction` (function) **required** An async function to make a request to your server to update the Checkout Session. ### Run server update ```jsx const checkoutState = useCheckout(); if (checkoutState.type === 'success') { const {runServerUpdate, id} = checkoutState.checkout; runServerUpdate( () => { return fetch('/update-checkout-session', { method: 'POST', body: JSON.stringify({checkoutSessionId: id}), }); } ); } ``` ## PaymentElement Use the `PaymentElement` from `@stripe/react-stripe-js/checkout` to collect payment details for more than [40 payment methods](/docs/payments/payment-methods/integration-options.md) from around the globe. The component must be rendered inside a [CheckoutProvider](/js/react_stripe_js/checkout/checkout_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Payment Element initialization options. - `fields` (object) By default, the Payment Element will collect only the necessary billing details to complete a payment. If you intend to collect billing details fields outside of the Payment Element, you can disable Payment Element collection of certain fields with the `fields` option. - `billingDetails` ('never' | 'auto' | object) Specify `never` to avoid collecting all [billing details](/api/payment_methods/object.md#payment_method_object-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` ('never' | 'auto') - `email` ('never' | 'auto') - `phone` ('never' | 'auto') - `address` ('never' | 'if_required' | 'auto' | object) 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` ('never' | 'auto') - `line2` ('never' | 'auto') - `city` ('never' | 'auto') The name of a city, town, village, etc. - `state` ('never' | 'auto') 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` ('never' | 'auto') Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2. - `postalCode` ('never' | 'auto') The postal code or ZIP code, also known as PIN code in India. - `layout` ('accordion' | 'tabs' | object) 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` ('accordion' | 'tabs') **required** Defines the layout to render the Payment Element. - `defaultCollapsed` (boolean) 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` ('always' | 'never' | 'if_multiple' | 'auto') 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` (boolean) When `true`, the Payment Methods render as standalone buttons with space in between them. _This property is only applicable to the `accordion` layout._ - `visibleAccordionItemsCount` (number) 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` ('start' | 'end') Sets the position of the payment method logo in each accordion item. Default is `start`. _This property is only applicable to the `accordion` layout._ - `paymentMethodOrder` (array) 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 Checkout Session 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. - `readOnly` (boolean) 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](/elements/appearance-api.md). - `terms` (object) 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` ('auto' | 'always' | 'never') - `auBecsDebit` ('auto' | 'always' | 'never') - `bancontact` ('auto' | 'always' | 'never') - `card` ('auto' | 'always' | 'never') - `cashapp` ('auto' | 'always' | 'never') - `googlePay` ('auto' | 'always' | 'never') - `ideal` ('auto' | 'always' | 'never') - `paypal` ('auto' | 'always' | 'never') - `sepaDebit` ('auto' | 'always' | 'never') - `sofort` ('auto' | 'always' | 'never') - `usBankAccount` ('auto' | 'always' | 'never') - `wallets` (object) By default, the Payment Element will display all the payment methods that the underlying Checkout Session was created with. However, wallets like Apple Pay and Google Pay are not payment methods per the Checkout Session API. They will show when the Checkout Session 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` ('auto' | 'never') - `googlePay` ('auto' | 'never') - `link` ('auto' | 'never') - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change?type=paymentElement.md#element_on_change-handler) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoaderStart` (function) Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - `onLoadError` (function) Callback called when the Element fails to load. ### Render PaymentElement ```jsx import React from 'react'; import {CheckoutProvider, PaymentElement} from '@stripe/react-stripe-js/checkout'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); const App = ({clientSecret}) => (
); export default App; ``` ## ExpressCheckoutElement Use the `ExpressCheckoutElement` from `@stripe/react-stripe-js/checkout` to accept payments through one-click payment buttons. The component must be rendered inside a [CheckoutProvider](/js/react_stripe_js/checkout/checkout_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Express Checkout Element initialization options. - `buttonHeight` (number) By default, the height of the buttons are 44px. You can override this to specify a custom button height in the range of 40px-55px. - `buttonTheme` (object) Specify the preferred button theme to use. By default, Elements determines the themes based on the specified [appearance option](/js/elements_object/create.md#stripe_elements-options-appearance). - `applePay` ('black' | 'white' | 'white-outline') - `googlePay` ('black' | 'white') - `paypal` ('gold' | 'blue' | 'silver' | 'white' | 'black') - `klarna` ('dark' | 'light' | 'outlined') - `buttonType` (object) Specify the preferred button type to display. - `applePay` ('add-money' | 'book' | 'buy' | 'check-out' | 'contribute' | 'donate' | 'order' | 'plain' | 'reload' | 'rent' | 'subscribe' | 'support' | 'tip' | 'top-up') Default is `plain`. - `googlePay` ('book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe') Default is `buy`. - `paypal` ('paypal' | 'checkout' | 'buynow' | 'pay') Default is `paypal`. - `klarna` ('continue' | 'pay') Default is `pay`. - `layout` (object) Specify how the buttons are arranged in a grid-like layout in the Express Checkout Element. Elements determines the layout by using certain factors, such as available space, number of buttons, and the defined `layout` object. - `maxColumns` (number) Defines the maximum number of columns the Express Checkout Element can use to render. Default is `0`, meaning unlimited. - `maxRows` (number) Defines the maximum number of rows the Express Checkout Element can use to render. Default is `0`, meaning unlimited. - `overflow` ('auto' | 'never') Specify whether or not to always hide the overflow menu or allow Elements to determine when to show the overflow menu. Default is `auto`. You can't specify both `overflow: 'never'` and set `maxRows` to a number greater than 0. - `paymentMethodOrder` (array) By default, the Express Checkout Element uses a dynamic ordering that optimizes payment method display for each user. You can override the default order in which payment methods display in the Express Checkout Element with a list of payment method types. If there are payment methods that will show that are not specified in `paymentMethodOrder`, they display after the payment methods you specify. If you specify payment methods that will not show, they are ignored. - `paymentMethods` (object) Besides your Dashboard configuration, the availability of payment methods in the Express Checkout Element is influenced by the CheckoutSession configuration. By default, it displays all available payment methods based on both configurations. When setting the paymentMethods option, the Express Checkout Element merges your specified options with the default logic to determine the final set of payment methods displayed. - `amazonPay` ('auto' | 'never') - `applePay` ('always' | 'auto' | 'never') Apple Pay has additional configurations that determine when Stripe can show it. By default, Apple Pay shows when the customer is using a supported platform and when we determine it's advantageous for your conversion. This is the `auto` behavior. If you want to always show Apple Pay when the customer is using a supported platform, you can set its property in `paymentMethods` to `always`. - `googlePay` ('always' | 'auto' | 'never') Google Pay has additional configurations that determine when Stripe can show it. By default, Google Pay shows when the customer is using a supported platform and when we determine it's advantageous for your conversion. This is the `auto` behavior. If you want to always show Google Pay when the customer is using a supported platform, you can set its property in `paymentMethods` to `always`. - `link` ('auto' | 'never') - `paypal` ('auto' | 'never') - `onConfirm` (function) **required** Triggered when the Element fires a confirm event. Use this to handle payment confirmation. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoadError` (function) Callback called when the Element fails to load. ### Render ExpressCheckoutElement ```jsx import React from 'react'; import {CheckoutProvider, ExpressCheckoutElement} from '@stripe/react-stripe-js/checkout'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); const App = ({clientSecret}) => ( { // Fulfill order once the payment is confirmed }} /> ); export default App; ``` ## BillingAddressElement Use the `BillingAddressElement` from `@stripe/react-stripe-js/checkout` to render and update the billing address on the current [Checkout Session](/api/checkout/sessions/object.md). The component must be rendered inside a [CheckoutProvider](/js/react_stripe_js/checkout/checkout_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Billing Address Element initialization options. - `contacts` (array) An array of [Contact](/js/appendix/contact_object.md) objects that can be displayed as saved addresses in the Billing Address Element. The first contact is automatically selected. - `display` (object) You can customize how certain fields are displayed. - `name` ('full' | 'split' | 'organization') By default, the Billing Address Element displays a full name field. Specify 'split' to display a first name field and a last name field. Specify 'organization' to display an organization field. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change?type=addressElement.md#element_on_change-handler) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoaderStart` (function) Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - `onLoadError` (function) Callback called when the Element fails to load. ### Render BillingAddressElement ```JSX import React from 'react'; import {CheckoutProvider, BillingAddressElement} from '@stripe/react-stripe-js/checkout'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); const App = ({clientSecret}) => ( ); export default App; ``` ## ShippingAddressElement Use the `ShippingAddressElement` from `@stripe/react-stripe-js/checkout` to render and update the shipping address on the current [Checkout Session](/api/checkout/sessions/object.md). The component must be rendered inside a [CheckoutProvider](/js/react_stripe_js/checkout/checkout_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Shipping Address Element initialization options. - `contacts` (array) An array of [Contact](/js/appendix/contact_object.md) objects that can be displayed as saved addresses in the Shipping Address Element. The first contact is automatically selected. - `display` (object) You can customize how certain fields are displayed. - `name` ('full' | 'split' | 'organization') By default, the Shipping Address Element displays a full name field. Specify 'split' to display a first name field and a last name field. Specify 'organization' to display an organization field. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change?type=addressElement.md#element_on_change-handler) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoaderStart` (function) Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - `onLoadError` (function) Callback called when the Element fails to load. ### Render ShippingAddressElement ```JSX import React from 'react'; import {CheckoutProvider, ShippingAddressElement} from '@stripe/react-stripe-js/checkout'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const ShippingAddressSection = ({clientSecret}) => ( ); ``` ## CurrencySelectorElement Use the `CurrencySelectorElement` from `@stripe/react-stripe-js/checkout` to allow customers to select the currency for their payment. The component must be rendered inside a [CheckoutProvider](/js/react_stripe_js/checkout/checkout_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoaderStart` (function) Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - `onLoadError` (function) Callback called when the Element fails to load. ### Render CurrencySelectorElement ```jsx import React from 'react'; import {CheckoutProvider, CurrencySelectorElement} from '@stripe/react-stripe-js/checkout'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); const App = ({clientSecret}) => ( ); export default App; ``` ## TaxIdElement Use the `TaxIdElement` from `@stripe/react-stripe-js/checkout` to collect tax ID information from your customers, including business name and tax identification number. The component must be rendered inside a [CheckoutProvider](/js/react_stripe_js/checkout/checkout_provider.md). > This feature requires the `custom_checkout_tax_id_1` beta. To use it, pass `betas: ['custom_checkout_tax_id_1']` when initializing Stripe.js via `loadStripe`. ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Tax ID Element initialization options. - `visibility` ('always' | 'never' | 'auto') By default, the Tax ID Element displays when the user is in a country that supports tax ID collection. Specify `always` to display the element regardless of the user's country. Specify `never` to hide the element completely. - `fields` (object) By default, the Tax ID Element collects all tax ID information. If it's not necessary for you to collect all fields, you can disable Tax ID Element collection of certain fields with the `fields` option. - `businessName` ('always' | 'never' | 'auto') Specify `always` to collect the business name. Specify `never` to not collect the business name. Default is `auto`. - `validation` (object) By default, the Tax ID Element will enforce preset validation for each field. You can customize the settings by using this option. - `businessName` (object) - `required` ('always' | 'never' | 'auto') Specify `always` to make business name a required field. Specify `never` to make business name an optional field. Default is `auto`. - `taxId` (object) - `required` ('always' | 'never' | 'auto') Specify `always` to make tax ID a required field. Specify `never` to make tax ID an optional field. Default is `auto`. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change?type=taxIdElement.md#element_on_change-handler) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoaderStart` (function) Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - `onLoadError` (function) Callback called when the Element fails to load. ### Render TaxIdElement ```jsx import React from 'react'; import {CheckoutProvider, TaxIdElement} from '@stripe/react-stripe-js/checkout'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}', { betas: ['custom_checkout_tax_id_1'], }); const App = ({clientSecret}) => ( { // Handle tax ID changes console.log('Tax ID changed:', event); }} /> ); export default App; ``` ## Using the Elements provider Build your Stripe integration using React and Stripe Elements. See [build a checkout page](/docs/payments/quickstart.md) for steps on using Elements with the [Payment Intents API](/api/payment_intents.md). The following React components and hooks are available to use as part of your integration. ## Elements `Elements` mounts the Stripe Elements context for `@stripe/react-stripe-js`. Wrap the portion of your React tree that renders individual Element components to make the Stripe object, Elements instance, and related helpers available via React context. For the [Payment Element created without an Intent](/payments/accept-a-payment-deferred.md), see the [ElementsProvider without an intent](/js/react_stripe_js/elements/elements_provider_without_intent.md) reference instead. ### Props - `stripe` (`Stripe` | Promise) **required** A [Stripe object](/js/initializing.md) or a `Promise` that resolves to one. The value returned from `loadStripe` is the recommended way to initialize this prop. - `options` (object) A set of options to create this `Elements` instance with. - `fonts` (array) An array of custom fonts, which elements created from the `Elements` object can use. Fonts can be specified as [CssFontSource](#css_font_source_object) or [CustomFontSource](#custom_font_source_object) objects. - `locale` (string) A [locale](#supported_locales) to display placeholders and error strings in. Default is `auto` (Stripe detects the locale of the browser). Setting the locale does not affect the behavior of postal code validation—a valid postal code for the billing country of the card is still required. To indicate the direction of text for *right to left* languages such as Arabic and Hebrew, mount Elements underneath an HTML element that includes the `dir="rtl"` attribute. - `clientSecret` (string) **required** Required to use with the [Payment Element](/payments/payment-element.md) and the [Link Authentication Element](/payments/link.md). The [client secret](/api/payment_intents/object.md#payment_intent_object-client_secret) for a PaymentIntent or SetupIntent. - `appearance` (object) Supported for the [Payment Element](/payments/payment-element.md), the [Link Authentication Element](/payments/link.md), and the [Address Element](/elements/address-element/.md). Match the design of your site with the [appearance option](/elements/appearance-api.md). The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more. - `loader` ('auto' | 'always' | 'never') Supported for the [Payment Element](/payments/payment-element.md), the [Link Authentication Element](/payments/link.md), and the [Address Element](/elements/address-element/.md). Display skeleton loader UI while waiting for Elements to be fully loaded, after they are mounted. Default is `'auto'` (Stripe determines if a loader UI should be shown). - `currency` (string) Used with the [Payment Element](/payments/payment-element.md). Influences available payment methods when creating SetupIntents with [automatic_payment_methods](/api/setup_intents/create.md#create_setup_intent-automatic_payment_methods). Payment Element renders the payment methods enabled in the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods) that support the provided currency. Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](/currencies.md). - `customerSessionClientSecret` (string) Used with the [Payment Element](/payments/payment-element.md) and [Address Element](/elements/address-element.md). The client_secret returned from create a [CustomerSession](/api/customer_sessions.md) associated with the [Customer ID](/api/customers/object.md#customer_object-id) for that session. - `syncAddressCheckbox` ('billing' | 'shipping' | 'none') Used with the [Address Element](/elements/address-element.md). The `syncAddressCheckbox` parameter configures which Address Element to show the checkbox above. The checkbox allows the customer the option to sync billing and shipping addresses when multiple Address Elements are used, one of each mode, in a single Elements instance. Default is `'billing'`. `'none'` opts out of showing the checkbox in either Address Element. - `paymentMethodCreation` ('manual') Used with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). Allows PaymentMethods to be created from the Elements instance using [stripe.createPaymentMethod](/js/payment_methods/create_payment_method_elements.md). **NOTE:** The Express Checkout Element doesn't support [stripe.createPaymentMethod](/js/payment_methods/create_payment_method_elements.md) with [Amazon Pay](/payments/amazon-pay.md) or [Klarna](/payments/klarna.md). Use [stripe.createConfirmationToken](/js/confirmation_tokens/create_confirmation_token.md) instead. Card installments are also unsupported and either blocks showing the plan selection UI, or raises an error for manual enablement using `paymentMethodOptions`. - `customPaymentMethods` (array) Supported for the [Payment Element](/payments/payment-element.md). An array of [custom payment methods](/payments/payment-element/custom-payment-methods.md) to display in the [Payment Element](/payments/payment-element.md). The custom payment methods must be registered in the [Stripe Dashboard](https://dashboard.stripe.com/settings/custom_payment_methods). - `id` (string) **required** The ID of the [custom payment method type](https://dashboard.stripe.com/settings/custom_payment_methods), prefixed with `cpmt_`. - `options` (object) A set of options to configure the custom payment method with. - `type` ('static') **required** The form type of the custom payment method. - `subtitle` (string) A subtitle contains additional information about the custom payment method. - `externalPaymentMethodTypes (deprecated)` (string) _This param has been deprecated in favor of [custom payment methods](/js/elements_object/create.md#stripe_elements-options-customPaymentMethods), which offers more flexibility._ The [external payment methods](/payments/external-payment-methods.md) to be displayed in the [Payment Element](/payments/payment-element.md) that you are already integrated with. Must be an [available external payment methods](/payments/external-payment-methods.md#available-external-payment-methods). - `children` (ReactNode) **required** `Elements` renders its children once the Stripe object and Elements instance are ready. ### Mount Elements ```jsx import React from 'react'; import {Elements} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret, children}) => ( {children} ); ``` ## Elements without an intent `Elements` mounts the Stripe Elements context for `@stripe/react-stripe-js`. Wrap the portion of your React tree that renders individual Element components to make the Stripe object, Elements instance, and related helpers available via React context. This reference applies to the [Payment Element created without an Intent](/payments/accept-a-payment-deferred.md), and [Card Elements](/payments/card-element.md). For other elements, see the [ElementsProvider](/js/react_stripe_js/elements/elements_provider.md) reference instead. ### Props - `stripe` (`Stripe` | Promise) **required** A [Stripe object](/js/initializing.md) or a `Promise` that resolves to one. The value returned from `loadStripe` is the recommended way to initialize this prop. - `options` (object) A set of options to create this `Elements` instance with. - `fonts` (array) An array of custom fonts, which elements created from the `Elements` object can use. Fonts can be specified as [CssFontSource](#css_font_source_object) or [CustomFontSource](#custom_font_source_object) objects. - `locale` (string) A [locale](#supported_locales) to display placeholders and error strings in. Default is `auto` (Stripe detects the locale of the browser). Setting the locale does not affect the behavior of postal code validation—a valid postal code for the billing country of the card is still required. To indicate the direction of text for *right to left* languages such as Arabic and Hebrew, mount Elements underneath an HTML element that includes the `dir="rtl"` attribute. - `mode` ('payment' | 'setup' | 'subscription') **required** Required to use with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). Filters out payment methods based on intended use. - `currency` (string) **required** Required to use with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](/currencies.md). - `amount` (number) **required** Used with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). Required when `mode` is `payment` or `subscription`. Shown in Apple Pay, Google Pay, or Buy now, pay later UIs. The amount intended to be collected from the customer right now. A positive integer representing how much to charge in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge 1.00 USD or 100 to charge 100 JPY, a zero-decimal currency). The minimum amount is 0.50 USD or [equivalent in charge currency](/currencies.md#minimum-and-maximum-charge-amounts). If `mode` is `subscription`, the value supports 0 to account for coupons and free trials, but any amount above 0 is subject to the minimum. The amount value supports up to eight digits (e.g., a value of 99999999 for a 999,999.99 USD charge). - `setupFutureUsage` ('on_session' | 'off_session') Used with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). Indicates that you intend to make future payments with the payment details collected by the Payment Element. This should match the [setup_future_usage](/api/payment_intents/create.md#create_payment_intent-setup_future_usage) provided on the Intent used when confirming payment. - `captureMethod` ('automatic' | 'automatic_async' | 'manual') Used with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). Influences available payment methods. This should match the [capture_method](/api/payment_intents/create.md#create_payment_intent-capture_method) provided on the Intent used when confirming payment. - `onBehalfOf` (string) Used with the [Payment Element](/payments/payment-element.md), [Express Checkout Element](/elements/express-checkout-element.md), and [Card Elements](/payments/card-element.md). The Stripe account ID which is the business of record. See [use cases](/connect/charges.md) to determine if this option is relevant for your integration. This should match the [on_behalf_of](/api/payment_intents/create.md#create_payment_intent-on_behalf_of) provided on the Intent used when confirming payment. - `paymentMethodTypes` (array) Used with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). A list of payment method types to render. You can omit this attribute to manage your payment methods from the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). - `paymentMethodConfiguration` (string) Used with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). The [payment method configuration](/api/payment_method_configurations.md) to use when managing your payment methods from the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). If none is specified, your default configuration is used. - `paymentMethodOptions` (object) Used with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). Additional payment-method-specific options for configuring behavior when initialized without an intent. - `acss_debit` (object) If this is an `acss_debit` PaymentMethod, this sub-hash contains details about the ACSS Debit payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `affirm` (object) If this is an `affirm` PaymentMethod, this sub-hash contains details about the Affirm payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `afterpay_clearpay` (object) If this is an `afterpay_clearpay` PaymentMethod, this sub-hash contains details about the Afterpay / Clearpay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `alipay` (object) If this is an `alipay` PaymentMethod, this sub-hash contains details about the Alipay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `alma` (object) If this is an `alma` PaymentMethod, this sub-hash contains details about the Alma payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `amazon_pay` (object) If this is an `amazon_pay` PaymentMethod, this sub-hash contains details about the Amazon Pay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `au_becs_debit` (object) If this is an `au_becs_debit` PaymentMethod, this sub-hash contains details about the BECS Debit payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `bacs_debit` (object) If this is a `bacs_debit` PaymentMethod, this sub-hash contains details about the Bacs Debit payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `bancontact` (object) If this is a `bancontact` PaymentMethod, this sub-hash contains details about the Bancontact payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `billie` (object) If this is a `billie` PaymentMethod, this sub-hash contains details about the Billie payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `blik` (object) If this is a `blik` PaymentMethod, this sub-hash contains details about the BLIK payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `boleto` (object) If this is a `boleto` PaymentMethod, this sub-hash contains details about the Boleto payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `card` (object) If this is a `card` PaymentMethod, this sub-hash contains details about the card payment method options. - `require_cvc_recollection` (boolean) When enabled, using a card that is attached to a customer will require the CVC to be provided again. When providing a `customerSessionClientSecret` and using the Payment Element, the Payment Element will prompt for CVC recollection. - `installments` (object) Installment configuration. - `enabled` (boolean) When `true`, shows the card installment plan selection UI (depending on issuer and country support) if you don't manage your payment methods in the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). You must set `mode='payment'` _and_ explicitly specify `paymentMethodTypes` in the Elements `options`. Setting installments to `true` without these settings returns an error. Incompatible with `paymentMethodCreation='manual'`. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `cashapp` (object) If this is a `cashapp` PaymentMethod, this sub-hash contains details about the Cash App Pay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `crypto` (object) If this is a `crypto` PaymentMethod, this sub-hash contains details about the Crypto payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `customer_balance` (object) If this is a `customer_balance` PaymentMethod, this sub-hash contains details about the Customer Balance payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `eps` (object) If this is an `eps` PaymentMethod, this sub-hash contains details about the EPS payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `fpx` (object) If this is an `fpx` PaymentMethod, this sub-hash contains details about the FPX payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `giropay` (object) If this is a `giropay` PaymentMethod, this sub-hash contains details about the giropay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `grabpay` (object) If this is a `grabpay` PaymentMethod, this sub-hash contains details about the GrabPay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `ideal` (object) If this is an `ideal` PaymentMethod, this sub-hash contains details about the iDEAL payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `kakao_pay` (object) If this is a `kakao_pay` PaymentMethod, this sub-hash contains details about the Kakao Pay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `klarna` (object) If this is a `klarna` PaymentMethod, this sub-hash contains details about the Klarna payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `konbini` (object) If this is a `konbini` PaymentMethod, this sub-hash contains details about the Konbini payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `kr_card` (object) If this is a `kr_card` PaymentMethod, this sub-hash contains details about the Korean card payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `link` (object) If this is a `link` PaymentMethod, this sub-hash contains details about the Link payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `mb_way` (object) If this is a `mb_way` PaymentMethod, this sub-hash contains details about the MB WAY payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `mobilepay` (object) If this is a `mobilepay` PaymentMethod, this sub-hash contains details about the MobilePay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `multibanco` (object) If this is a `multibanco` PaymentMethod, this sub-hash contains details about the Multibanco payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `naver_pay` (object) If this is a `naver_pay` PaymentMethod, this sub-hash contains details about the Naver Pay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `netbanking` (object) If this is a `netbanking` PaymentMethod, this sub-hash contains details about the NetBanking payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `nz_bank_account` (object) If this is a `nz_bank_account` PaymentMethod, this sub-hash contains details about the New Zealand bank account payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `oxxo` (object) If this is an `oxxo` PaymentMethod, this sub-hash contains details about the OXXO payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `p24` (object) If this is a `p24` PaymentMethod, this sub-hash contains details about the Przelewy24 payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `paynow` (object) If this is a `paynow` PaymentMethod, this sub-hash contains details about the PayNow payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `pix` (object) If this is a `pix` PaymentMethod, this sub-hash contains details about the Pix payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `paypal` (object) If this is a `paypal` PaymentMethod, this sub-hash contains details about the PayPal payment method options. - `capture_method` ('automatic' | 'manual') Controls when the funds will be captured. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `promptpay` (object) If this is a `promptpay` PaymentMethod, this sub-hash contains details about the PromptPay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `revolut_pay` (object) If this is a `revolut_pay` PaymentMethod, this sub-hash contains details about the Revolut Pay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `satispay` (object) If this is a `satispay` PaymentMethod, this sub-hash contains details about the Satispay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `sepa_debit` (object) If this is a `sepa_debit` PaymentMethod, this sub-hash contains details about the SEPA Debit payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `sofort` (object) If this is a `sofort` PaymentMethod, this sub-hash contains details about the Sofort payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `sunbit` (object) If this is a `sunbit` PaymentMethod, this sub-hash contains details about the Sunbit payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `swish` (object) If this is a `swish` PaymentMethod, this sub-hash contains details about the Swish payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `twint` (object) If this is a `twint` PaymentMethod, this sub-hash contains details about the TWINT payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `upi` (object) If this is a `upi` PaymentMethod, this sub-hash contains details about the UPI payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `us_bank_account` (object) If this is a `us_bank_account` PaymentMethod, this sub-hash contains details about the US bank account payment method options. - `verification_method` ('automatic' | 'instant') Verification method for the US bank account collection flow - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `off_session` (string) Use `off_session` if your customer may or may not be present in your checkout flow. - `on_session` (string) Use `on_session` if you intend to only reuse the payment method when your customer is present in your checkout flow. - `financial_connections` (object) Additional fields for Financial Connections session creation - `permissions` (array) The list of permissions to request. If this parameter is passed, the `payment_method` permission must be included. Valid permissions include: `balances`, `ownership`, `payment_method`, and `transactions`. - `prefetch` (array) The list of permissions that you would like to retrieve upon creation. Valid permissions include: `balances`, `ownership`, and `transactions`. - `wechat_pay` (object) If this is a `wechat_pay` PaymentMethod, this sub-hash contains details about the WeChat Pay payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `zip` (object) If this is a `zip` PaymentMethod, this sub-hash contains details about the Zip payment method options. - `setup_future_usage` (enum) Indicates that you intend to make future payments with the payment details collected by the Payment Element. - `none` (string) Use `none` if you do not intend to reuse this payment method and want to override the top-level setup_future_usage value for this payment method. - `appearance` (object) Supported for the [Payment Element](/payments/payment-element.md), the [Link Authentication Element](/payments/link.md), the [Express Checkout Element](/elements/express-checkout-element.md), and the [Address Element](/elements/address-element/.md). Match the design of your site with the [appearance option](/elements/appearance-api.md). The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more. - `loader` ('auto' | 'always' | 'never') Supported for the [Payment Element](/payments/payment-element.md), the [Link Authentication Element](/payments/link.md), and the [Address Element](/elements/address-element/.md). Display skeleton loader UI while waiting for Elements to be fully loaded, after they are mounted. Default is `'auto'` (Stripe determines if a loader UI should be shown). - `customerSessionClientSecret` (string) Used with the [Payment Element](/payments/payment-element.md) and [Address Element](/elements/address-element.md). The client_secret returned from create a [CustomerSession](/api/customer_sessions.md) associated with the [Customer ID](/api/customers/object.md#customer_object-id) for that session. - `syncAddressCheckbox` ('billing' | 'shipping' | 'none') Used with the [Address Element](/elements/address-element.md). The `syncAddressCheckbox` parameter configures which Address Element to show the checkbox above. The checkbox allows the customer the option to sync billing and shipping addresses when multiple Address Elements are used, one of each mode, in a single Elements instance. Default is `'billing'`. `'none'` opts out of showing the checkbox in either Address Element. - `paymentMethodCreation` ('manual') Used with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). Allows PaymentMethods to be created from the Elements instance using [stripe.createPaymentMethod](/js/payment_methods/create_payment_method_elements.md). **NOTE:** The Express Checkout Element doesn't support [stripe.createPaymentMethod](/js/payment_methods/create_payment_method_elements.md) with [Amazon Pay](/payments/amazon-pay.md) or [Klarna](/payments/klarna.md). Use [stripe.createConfirmationToken](/js/confirmation_tokens/create_confirmation_token.md) instead. Card installments are also unsupported and either blocks showing the plan selection UI, or raises an error for manual enablement using `paymentMethodOptions`. - `excludedPaymentMethodTypes` (array) Used with the [Payment Element](/payments/payment-element.md) and [Express Checkout Element](/elements/express-checkout-element.md). The list of payment method types to exclude from use with this payment. - `customPaymentMethods` (array) Supported for the [Payment Element](/payments/payment-element.md). An array of [custom payment methods](/payments/payment-element/custom-payment-methods.md) to display in the [Payment Element](/payments/payment-element.md). The custom payment methods must be registered in the [Stripe Dashboard](https://dashboard.stripe.com/settings/custom_payment_methods). - `id` (string) **required** The ID of the [custom payment method type](https://dashboard.stripe.com/settings/custom_payment_methods), prefixed with `cpmt_`. - `options` (object) A set of options to configure the custom payment method with. - `type` ('static') **required** The form type of the custom payment method. - `subtitle` (string) A subtitle contains additional information about the custom payment method. - `children` (ReactNode) **required** `Elements` renders its children once the Stripe object and Elements instance are ready. ### Mount Elements ```jsx import React from 'react'; import {Elements} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({children}) => ( const options = { mode: 'payment', currency: 'usd', amount: 1099, }; {children} ); ``` ## useStripe hook The `useStripe` hook returns the initialized [Stripe.js](/js/initializing.md) instance from the `Elements` provider. Use it to [confirm payments](/js/payment_intents/confirm_payment.md) and call other Stripe.js methods from inside your React components. If you need to access the Stripe object from a class component, use [ElementsConsumer](/react_stripe_js/elements/elements_consumer.md) instead. ### Return value - `result` (Stripe | null) **required** Returns the `Stripe` instance configured on the [provider](/js/elements/elements_provider.md), or `null` while it is still loading. ### Call useStripe ```jsx import React from 'react'; import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js'; export const PaymentForm = () => { const stripe = useStripe(); const elements = useElements(); const handleSubmit = async (event) => { event.preventDefault(); if (!stripe || !elements) { return; } // Use the `Stripe` instance to confirm the payment await stripe.confirmPayment({ elements, confirmParams: { return_url: 'https://example.com/order/123/complete', }, }); }; return (
); }; ``` ## useElements To safely pass the payment information collected by the Payment Element to the Stripe API, access the `Elements` instance so that you can use it with `stripe.confirmPayment`. If you need to access an Element from a class component, use [ElementsConsumer](/react_stripe_js/elements/elements_consumer.md) instead. ### Return value - `result` (Elements | null) **required** Returns the current `Elements` instance or `null` while the provider is still loading. ### Call useElements ```jsx import React from 'react'; import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js'; export const PaymentForm = () => { const stripe = useStripe(); const elements = useElements(); const handleSubmit = async (event) => { event.preventDefault(); if (!stripe || !elements) { return; } await stripe.confirmPayment({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: 'https://example.com/order/123/complete', }, }); }; return (
); }; ``` ## ElementsConsumer `ElementsConsumer` exposes the same `Stripe` and `Elements` instances as the [hooks](/js/elements/use_stripe.md), but uses a render prop instead of React hooks. This is useful when building class components or when you prefer the render-prop pattern. ### Props - `children` (({stripe: Stripe | null, elements: Elements | null}) => ReactNode) **required** A render prop that receives `{stripe, elements}`. Render your UI using these instances. ### Render ElementsConsumer ```JSX import React from 'react'; import {ElementsConsumer, PaymentElement} from '@stripe/react-stripe-js'; class CheckoutForm extends React.Component { render() { const {stripe, elements} = this.props; return (
); } } // Wrap your class component in ElementsConsumer to inject props export default class WrappedCheckoutForm extends React.Component { render() { return ( {({stripe, elements}) => ( )} ); } } ``` ## PaymentElement Use the `PaymentElement` from `@stripe/react-stripe-js` to collect payment details for more than [40 payment methods](/docs/payments/payment-methods/integration-options.md) from around the globe. The component must be rendered inside an [Elements Provider](/js/react_stripe_js/elements/elements_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Options for creating the Payment Element. - `layout` ('accordion' | 'tabs' | object) 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` ('accordion' | 'tabs') **required** Defines the layout to render the Payment Element. - `defaultCollapsed` (boolean) 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` ('always' | 'never' | 'if_multiple' | 'auto') 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` (boolean) When `true`, the Payment Methods render as standalone buttons with space in between them. _This property is only applicable to the `accordion` layout._ - `visibleAccordionItemsCount` (number) 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` ('start' | 'end') 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` (object) Provide initial customer information that will be displayed in the Payment Element. The form will render with empty fields if not provided. - `billingDetails` (object) 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` (string) - `email` (string) - `phone` (string) - `address` (object) - `line1` (string) - `line2` (string) - `city` (string) The name of a city, town, village, etc. - `state` (string) 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` (string) Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2. - `postal_code` (string) The postal code or ZIP code, also known as PIN code in India. - `paymentMethods` (object) Specify customer's default information for different payment methods. Pre-filling as much information as possible streamlines the checkout process. - `ideal` (object) - `bank` (string) A pre-filled iDEAL bank value for the Payment Element. Can only be one of the banks listed in the [iDEAL guide](/payments/ideal/accept-a-payment?ui=element.md#bank-reference) (e.g., `abn_amro`). - `payto` (object) - `usePayId` (boolean) 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` (object) Specify default settings for card payments. - `network` (array) Specifies a network preference for [Card Brand Choice](/card-brand-choice.md). 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](/api/payment_methods/create.md#create_payment_method-card-networks-preferred) for valid values. - `business` (object) 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` (string) The name of your business. Your business name will be used to render mandate text for some payment methods. - `paymentMethodOrder` (array) 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` (object) By default, the Payment Element will collect all necessary details to complete a payment. For some payment methods, this means that the Payment Element will collect details like name or email that you may have already collected from the user. If this is the case, you can prevent the Payment Element from collecting these data by using the `fields` option. If you disable the collection of a certain field with the `fields` option, you must pass that same data to [stripe.confirmPayment](/js/payment_intents/confirm_payment.md) or the payment will be rejected. Learn more about how to [customize which billing details to collect](/payments/payment-element/control-billing-details-collection.md) and see [below](/js/elements_object/create_payment_element.md#payment_element_create-customized_fields) for details. - `billingDetails` ('never' | 'auto' | object) Specify `never` to avoid collecting all [billing details](/api/payment_methods/object.md#payment_method_object-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` ('never' | 'auto') - `email` ('never' | 'auto') - `phone` ('never' | 'auto') - `address` ('never' | 'if_required' | 'auto' | object) 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` ('never' | 'auto') - `line2` ('never' | 'auto') - `city` ('never' | 'auto') The name of a city, town, village, etc. - `state` ('never' | 'auto') 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` ('never' | 'auto') Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2. - `postalCode` ('never' | 'auto') The postal code or ZIP code, also known as PIN code in India. - `readOnly` (boolean) 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](/elements/appearance-api.md). - `terms` (object) 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` ('auto' | 'always' | 'never') - `auBecsDebit` ('auto' | 'always' | 'never') - `bancontact` ('auto' | 'always' | 'never') - `card` ('auto' | 'always' | 'never') - `cashapp` ('auto' | 'always' | 'never') - `googlePay` ('auto' | 'always' | 'never') - `ideal` ('auto' | 'always' | 'never') - `paypal` ('auto' | 'always' | 'never') - `sepaDebit` ('auto' | 'always' | 'never') - `sofort` ('auto' | 'always' | 'never') - `usBankAccount` ('auto' | 'always' | 'never') - `wallets` (object) 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` ('auto' | 'never') - `googlePay` ('auto' | 'never') - `link` ('auto' | 'never') - `applePay` (object) Specify Apple Pay specific options. These are passed through to the Apple Pay API. - `recurringPaymentRequest` (object) Specify a request to set up a recurring payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayrecurringpaymentrequest) for more details. - `paymentDescription` (string) **required** - `managementURL` (string) **required** - `regularBilling` (object) **required** - `amount` (number) **required** - `label` (string) **required** - `recurringPaymentStartDate` (Date) - `recurringPaymentEndDate` (Date) - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute') - `recurringPaymentIntervalCount` (number) - `trialBilling` (object) - `amount` (number) **required** - `label` (string) **required** - `recurringPaymentStartDate` (Date) - `recurringPaymentEndDate` (Date) - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute') - `recurringPaymentIntervalCount` (number) - `billingAgreement` (string) - `deferredPaymentRequest` (object) Specify a request to set up a deferred payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaydeferredpaymentrequest) for more details. - `paymentDescription` (string) **required** - `managementURL` (string) **required** - `deferredBilling` (object) **required** - `amount` (number) **required** - `label` (string) **required** - `deferredPaymentDate` (Date) **required** - `billingAgreement` (string) - `freeCancellationDate` (Date) If set, you must also supply a freeCancellationDateTimeZone., - `freeCancellationDateTimeZone` (string) "If set, you must also supply a freeCancellationDate., - `automaticReloadPaymentRequest` (object) Specify a request to set up an automatic reload payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayautomaticreloadpaymentrequest) for more details. - `paymentDescription` (string) **required** - `managementURL` (string) **required** - `automaticReloadBilling` (object) **required** - `amount` (number) **required** - `label` (string) **required** - `automaticReloadPaymentThresholdAmount` (Date) **required** - `billingAgreement` (string) - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change?type=paymentElement.md#element_on_change-handler) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoaderStart` (function) Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - `onLoadError` (function) Callback called when the Element fails to load. ### Render PaymentElement ```jsx import React from 'react'; import {ElementsProvider, PaymentElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => (
); ``` ## ExpressCheckoutElement Use the `ExpressCheckoutElement` from `@stripe/react-stripe-js` to accept payments through one-click payment buttons. The component must be rendered inside an [Elements Provider](/js/react_stripe_js/elements/elements_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Options for creating the Express Checkout Element. - `allowedShippingCountries` (array) By default, the Express Checkout Element allows all countries for shipping. You can specify which countries are allowed for shipping in the Express Checkout Element with a list of two-letter country codes. - `applePay` (object) Specify Apple Pay specific options. These are passed through to the Apple Pay API. - `recurringPaymentRequest` (object) Specify a request to set up a recurring payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayrecurringpaymentrequest) for more details. - `paymentDescription` (string) **required** - `managementURL` (string) **required** - `regularBilling` (object) **required** - `amount` (number) **required** - `label` (string) **required** - `recurringPaymentStartDate` (Date) - `recurringPaymentEndDate` (Date) - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute') - `recurringPaymentIntervalCount` (number) - `trialBilling` (object) - `amount` (number) **required** - `label` (string) **required** - `recurringPaymentStartDate` (Date) - `recurringPaymentEndDate` (Date) - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute') - `recurringPaymentIntervalCount` (number) - `billingAgreement` (string) - `deferredPaymentRequest` (object) Specify a request to set up a deferred payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaydeferredpaymentrequest) for more details. - `paymentDescription` (string) **required** - `managementURL` (string) **required** - `deferredBilling` (object) **required** - `amount` (number) **required** - `label` (string) **required** - `deferredPaymentDate` (Date) **required** - `billingAgreement` (string) - `freeCancellationDate` (Date) If set, you must also supply a freeCancellationDateTimeZone. - `freeCancellationDateTimeZone` (string) If set, you must also supply a freeCancellationDate. These are [tz](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) timezones such as `America/Los_Angeles`, `Europe/Dublin`, and `Asia/Singapore`. - `automaticReloadPaymentRequest` (object) Specify a request to set up an automatic reload payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayautomaticreloadpaymentrequest) for more details. - `paymentDescription` (string) **required** - `managementURL` (string) **required** - `automaticReloadBilling` (object) **required** - `amount` (number) **required** - `label` (string) **required** - `automaticReloadPaymentThresholdAmount` (number) **required** - `billingAgreement` (string) - `billingAddressRequired` (boolean) Controls whether the Express Checkout Element collects the billing address. The default value depends on your integration: - If you pass `allowedShippingCountries`, `phoneNumberRequired`, `shippingAddressRequired`, `emailRequired`, `applePay`, `lineItems`, or `business` when creating the Express Checkout Element, `billingAddressRequired` defaults to false. - Otherwise, `billingAddressRequired` defaults to true. You can explicitly set `billingAddressRequired` to true or false to override the default behavior. We highly recommend that you collect the billing address because it can be used to perform address verifications and block fraudulent payments. - `business` (object) Provide information about your business that's displayed in the Express Checkout Element. This information will be retrieved from your Stripe account if it's not provided. - `name` (string) The name of your business. Your business name is used to signal to the customer who they're paying. Klarna always retrieves the business name from your Stripe account, even when this option is set. - `buttonHeight` (number) By default, the height of the buttons are 44px. You can override this to specify a custom button height in the range of 40px-55px. - `buttonTheme` (object) Specify the preferred button theme to use. By default, Elements determines the themes based on the specified [appearance option](/js/elements_object/create.md#stripe_elements-options-appearance). - `applePay` ('black' | 'white' | 'white-outline') - `googlePay` ('black' | 'white') - `paypal` ('gold' | 'blue' | 'silver' | 'white' | 'black') - `klarna` ('dark' | 'light' | 'outlined') - `buttonType` (object) Specify the preferred button type to display. - `applePay` ('add-money' | 'book' | 'buy' | 'check-out' | 'contribute' | 'donate' | 'order' | 'plain' | 'reload' | 'rent' | 'subscribe' | 'support' | 'tip' | 'top-up') Default is `plain`. - `googlePay` ('book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe') Default is `buy`. - `paypal` ('paypal' | 'checkout' | 'buynow' | 'pay') Default is `paypal`. - `klarna` ('continue' | 'pay') Default is `pay`. - `emailRequired` (boolean) Collect the customer's email by setting this option to `true`. - `layout` (object) Specify how the buttons are arranged in a grid-like layout in the Express Checkout Element. Elements determines the layout by using certain factors, such as available space, number of buttons, and the defined `layout` object. - `maxColumns` (number) Defines the maximum number of columns the Express Checkout Element can use to render. Default is `0`, meaning unlimited. - `maxRows` (number) Defines the maximum number of rows the Express Checkout Element can use to render. Default is `0`, meaning unlimited. - `overflow` ('auto' | 'never') Specify whether or not to always hide the overflow menu or allow Elements to determine when to show the overflow menu. Default is `auto`. You can't specify both `overflow: 'never'` and set `maxRows` to a number greater than 0. - `lineItems` (array) An array of LineItem objects. These LineItems are shown as line items in the payment interface, if line items are supported. You can represent discounts as negative amount LineItems. - `name` (string) **required** The name of the line item surfaced to the customer in the payment interface. - `amount` (number) **required** The amount in the currency's subunit (for example, cents, yen, etc.). - `paymentMethods` (object) By default, the Express Checkout Element displays all payment methods possible as a result of your Dashboard configuration. This is the `auto` behavior. If you don't want to show a given payment method as a payment option, set its property in `paymentMethods` to `never`. - `amazonPay` ('auto' | 'never') - `applePay` ('always' | 'auto' | 'never') Apple Pay has additional configurations that determine when Stripe can show it. By default, Apple Pay shows when the customer is using a supported platform and when we determine it's advantageous for your conversion. This is the `auto` behavior. If you want to always show Apple Pay when the customer is using a supported platform, you can set its property in `paymentMethods` to `always`. This causes Apple Pay to be shown in supported browsers even when the customer isn't logged in to Apple Pay, resulting in a sign-in flow. Apple Pay on desktop Chromium browsers is only supported on MacOS when its property in `paymentMethods` is set to `always`. - `googlePay` ('always' | 'auto' | 'never') Google Pay has additional configurations that determine when Stripe can show it. By default, Google Pay shows when the customer is using a supported platform and when we determine it's advantageous for your conversion. This is the `auto` behavior. If you want to always show Google Pay when the customer is using a supported platform, you can set its property in `paymentMethods` to `always`. This causes Google Pay to be shown in supported browsers even when the customer isn't logged in to Google Pay, resulting in a sign-in flow. - `link` ('auto' | 'never') - `paypal` ('auto' | 'never') - `klarna` ('auto' | 'never') - `paymentMethodOrder` (array) By default, the Express Checkout Element uses a dynamic ordering that optimizes payment method display for each user. You can override the default order in which payment methods display in the Express Checkout Element with a list of payment method types. If there are payment methods that will show that are not specified in `paymentMethodOrder`, they display after the payment methods you specify. If you specify payment methods that will not show, they are ignored. - `phoneNumberRequired` (boolean) Collect the customer's phone number 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. - `shippingAddressRequired` (boolean) Collect the customer's shipping address by setting this option to `true`. If `true`, you must also supply a valid `shippingRates` option in either the `create`, `click`, or `shippingaddresschange` events. - `shippingRates` (array) An array of ShippingRate objects. The first shipping rate listed appears in the payment interface as the default option. - `id` (string) **required** Unique identifier for the object. - `amount` (number) **required** The amount to charge for shipping. - `displayName` (string) **required** The name of the shipping rate, displayed to the customer in the payment interface. - `deliveryEstimate` (object | string) The estimated range for how long shipping takes, displayed to the customer in the payment interface. We recommended using the object format, but you can use a string instead. - `maximum` (object) The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite). - `unit` ('hour' | 'day' | 'business_day' | 'week' | 'month') A unit of time. - `value` (number) Must be greater than 0. - `minimum` (object) The lower bound of the estimated range. If empty, it represents no lower bound. - `unit` ('hour' | 'day' | 'business_day' | 'week' | 'month') A unit of time. - `value` (number) Must be greater than 0. - `onConfirm` (function) **required** The [confirm](/js/elements_object/express_checkout_element_confirm_event.md) event is triggered from an Express Checkout Element when the customer finalizes their payment. - `onClick` (function) The [click](/js/elements_object/express_checkout_element_click_event.md) event is triggered from an Express Checkout Element when the customer clicks a payment button. - `onCancel` (function) The `cancel` event is triggered from an Express Checkout Element when the payment interface is dismissed. Note that in some browsers, the payment interface might be dismissed by the customer even after they authorize the payment. This means that you might receive a `cancel` event after receiving a `confirm` event. If you're using the `cancel` event as a hook for canceling the customer's order, make sure you also refund the payment that you just created. - `onShippingAddressChange` (function) Triggered when a customer changes their shipping address. - `onShippingRateChange` (function) Triggered when a customer changes their shipping rate. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoadError` (function) Callback called when the Element fails to load. ### Render ExpressCheckoutElement ```jsx import React from 'react'; import {Elements, ExpressCheckoutElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => ( { // Fulfill order once the payment is confirmed }} /> ); ``` ## AddressElement Use the `AddressElement` from `@stripe/react-stripe-js` to collect local and international billing and shipping addresses. The component must be rendered inside an [Elements Provider](/js/react_stripe_js/elements/elements_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) **required** Options for creating the Address Element. - `mode` ('shipping' | 'billing') **required** Specify which mode you would like to use Address Element for. When `shipping` mode is used with the Payment Element and Link Authentication Element, it will automatically pass shipping information when confirming Payment Intent or Setup Intent. When `billing` mode is used with the Payment Element, it will automatically pass the billing information when confirming Payment Intent or Setup Intent. - `autocomplete` (object) By default, the Address Element will have autocomplete enabled with Stripe provided Google Maps API key for certain countries if any of the following condition is met: * If Payment Element is mounted in the same elements group as Address Element in a single page application. * If the Address Element is used in an active Link session. [Contact Legal before editing or deleting the Google Maps autocomplete callout]: # By using autocomplete, you agree to comply with the [Google Maps Platform Acceptable Use Policy](https://cloud.google.com/maps-platform/terms/aup). If you violate this policy, we might disable autocomplete, or take any other action as necessary. You can customize the autocomplete setting with this option. - `mode` (‘automatic’ | ‘disabled’ | ‘google_maps_api’) **required** Specify `disabled` to disable autocomplete in the Address Element. Specify `google_maps_api` to enable [Google Maps API](https://developers.google.com/maps/documentation/javascript/places) with your own key. It will only be used when Stripe provided Google Maps API key is not available. The default setting is `automatic`, where we’ll support autocomplete when possible. - `apiKey` (string) Specify your own [Google Maps API key](https://developers.google.com/maps/documentation/javascript/places#add-places-api-to-the-api-keys-api-restrictions-list) with it. **Only needs to be passed in when `autocomplete.mode` is set to `google_maps_api`.** - `allowedCountries` (array) By default, the Address Element will display all countries for selection. You can specify which countries are displayed in the Address Element with a list of two-letter country codes. If only one country is specified, the country field will not display. - `blockPoBox` (boolean) By default, PO boxes are considered a valid address type. You can override this to invalidate PO Boxes. - `contacts` (array) An array of [Contact](/js/appendix/contact_object.md) objects that can be displayed as saved addresses in the Address Element. The first contact will be automatically selected. If using a [CustomerSession](/api/customer_sessions.md), Address Element will ignore contacts and render saved billing addresses instead. - `defaultValues` (object) Provide the initial information that will be displayed in the Address Element. The form will render with empty fields if not provided. - `name` (string) Provide the initial full name or organization name. - `firstName` (string) Provide the initial first name. The [display.name](/js/elements_object/create_address_element.md#address_element_create-options-display-name) option must be set to `split` if this property is specified. - `lastName` (string) Provide the initial last name. The [display.name](/js/elements_object/create_address_element.md#address_element_create-options-display-name) option must be set to `split` if this property is specified. - `phone` (string) Provide the initial phone number value. The [fields.phone](/js/elements_object/create_address_element.md#address_element_create-options-fields-phone) option must be set to `always` if this property is specified. - `address` (object) Provide the initial address details. - `line1` (string) - `line2` (string) - `city` (string) - `state` (string) - `postal_code` (string) - `country` (string) **required** - `fields` (object) By default, the Address Element will collect all the necessary information needed for an address. In some cases, it might be necessary to collect other types of information. You can specify other types of fields to render in the form with this option. - `phone` ('always' | 'auto' | 'never') Specify `always` to enable phone number collection in the Address Element. Only collect phone numbers if you need them for the transaction. Default is `auto`. - `validation` (object) By default, the Address Element will enforce preset validation for each field. You can customize the settings by using this option. - `phone` (object) - `required` ('always' | 'auto' | 'never') Specify `always` to make phone number a required field. The [fields.phone](/js/elements_object/create_address_element.md#address_element_create-options-fields-phone) option must be set to `always` if this property is specified. Default is `auto`. - `display` (object) You can customize how certain fields are displayed. - `name` ('full' | 'split' | 'organization') By default, the Address Element will display a full name field. Specify 'split' to display a first name field and a last name field. Specify 'organization' to display an organization field. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change?type=addressElement.md#element_on_change-handler) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoaderStart` (function) Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - `onLoadError` (function) Callback called when the Element fails to load. ### Render AddressElement ```jsx import React from 'react'; import {Elements, AddressElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => ( ); ``` ## LinkAuthenticationElement Use the `LinkAuthenticationElement` from `@stripe/react-stripe-js` to collect email addresses and allow users to log into Link on your checkout page. The component must be rendered inside an [Elements Provider](/js/react_stripe_js/elements/elements_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Options for creating the Link Authentication Element. - `defaultValues` (object) Provide the initial contact information that will be displayed in the Link Authentication Element. The form will render with empty fields if not provided. - `email` (string) - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change?type=linkAuthenticationElement.md#element_on_change-handler) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoaderStart` (function) Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - `onLoadError` (function) Callback called when the Element fails to load. ### Render LinkAuthenticationElement ```jsx import React from 'react'; import {Elements, LinkAuthenticationElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => ( ); ``` ## TaxIdElement Use the `TaxIdElement` from `@stripe/react-stripe-js` to collect tax ID information from your customers, including business name and tax identification number. The component must be rendered inside an [Elements Provider](/js/react_stripe_js/elements/elements_provider.md). ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Tax ID Element initialization options. - `visibility` ('always' | 'never' | 'auto') By default, the Tax ID Element displays when the user is in a country that supports tax ID collection. Specify `always` to display the element regardless of the user's country. Specify `never` to hide the element completely. - `fields` (object) By default, the Tax ID Element collects all tax ID information. If it's not necessary for you to collect all fields, you can disable Tax ID Element collection of certain fields with the `fields` option. - `businessName` ('always' | 'never' | 'auto') Specify `always` to collect the business name. Specify `never` to not collect the business name. Default is `auto`. - `validation` (object) By default, the Tax ID Element will enforce preset validation for each field. You can customize the settings by using this option. - `businessName` (object) - `required` ('always' | 'never' | 'auto') Specify `always` to make business name a required field. Specify `never` to make business name an optional field. Default is `auto`. - `taxId` (object) - `required` ('always' | 'never' | 'auto') Specify `always` to make tax ID a required field. Specify `never` to make tax ID an optional field. Default is `auto`. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change?type=taxIdElement.md#element_on_change-handler) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoaderStart` (function) Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - `onLoadError` (function) Callback called when the Element fails to load. ### Render TaxIdElement ```jsx import React from 'react'; import {Elements, TaxIdElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => ( ); ``` ## Other Element Components Additional Element wrappers from `@stripe/react-stripe-js` provide specialized payment methods and input fields. Use these components inside an [Elements Provider](/js/react_stripe_js/elements/elements_provider.md) alongside the standard Element set when you need to support specific payment experiences. ## AuBankAccountElement Use the `AuBankAccountElement` from `@stripe/react-stripe-js` to collect Australian bank account information (BSB and account number) for use with BECS Direct Debit payments. ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Options for creating an `auBankAccount` element. - `classes` (object) Set custom class names on the container DOM element when the Stripe element is in a particular state. - `base` (string) The base class applied to the container. Defaults to `StripeElement`. - `complete` (string) The class name to apply when the `Element` is complete. Defaults to `StripeElement--complete`. - `empty` (string) The class name to apply when the `Element` is empty. Defaults to `StripeElement--empty`. - `focus` (string) The class name to apply when the `Element` is focused. Defaults to `StripeElement--focus`. - `invalid` (string) The class name to apply when the `Element` is invalid. Defaults to `StripeElement--invalid`. - `webkitAutofill` (string) The class name to apply when the `Element` has its value autofilled by the browser (only on Chrome and Safari). Defaults to `StripeElement--webkit-autofill`. - `style` (object) Customize the appearance of this element using CSS properties passed in a [Style](/js/appendix/style.md) object. - `iconStyle` (string) Appearance of the icon in the Element. Either `solid` or `default`. - `hideIcon` (boolean) Hides the icon in the Element. Default is `false`. - `disabled` (boolean) Applies a disabled state to the Element such that user input is not accepted. Default is `false`. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change.md?type=auBankAccountElement) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. ### Render AuBankAccountElement ```JSX import React from 'react'; import {Elements, AuBankAccountElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => ( ); ``` ## CardElement Use the `CardElement` from `@stripe/react-stripe-js` to collect card details with automatic validation. ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Options for creating a `card` element. - `classes` (object) Set custom class names on the container DOM element when the Stripe element is in a particular state. - `base` (string) The base class applied to the container. Defaults to `StripeElement`. - `complete` (string) The class name to apply when the `Element` is complete. Defaults to `StripeElement--complete`. - `empty` (string) The class name to apply when the `Element` is empty. Defaults to `StripeElement--empty`. - `focus` (string) The class name to apply when the `Element` is focused. Defaults to `StripeElement--focus`. - `invalid` (string) The class name to apply when the `Element` is invalid. Defaults to `StripeElement--invalid`. - `webkitAutofill` (string) The class name to apply when the `Element` has its value autofilled by the browser (only on Chrome and Safari). Defaults to `StripeElement--webkit-autofill`. - `style` (object) Customize the appearance of this element using CSS properties passed in a [Style](/js/appendix/style.md) object. - `value` (object) A pre-filled set of values to include in the input. Note that sensitive card information (card number, CVC, and expiration date) cannot be pre-filled. - `postalCode` (string) - `hidePostalCode` (boolean) Hide the postal code field. Default is `false`. If you are already collecting a full billing address or postal code elsewhere, set this to `true`. - `iconStyle` (string) Appearance of the icon in the Element. Either `solid` or `default`. - `hideIcon` (boolean) Hides the icon in the Element. Default is `false`. - `disabled` (boolean) Applies a disabled state to the Element such that user input is not accepted. Default is `false`. - `disableLink` (boolean) Disables and hides the Link button in the Element. Default is `false`. You can also disable Link across all instances of `card` and `cardNumber` elements in your [payment method settings](https://dashboard.stripe.com/settings/payment_methods). - `preferredNetwork` (array) Specifies a network preference for [Card Brand Choice](/card-brand-choice.md). 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](/api/payment_methods/create.md#create_payment_method-card-networks-preferred) for valid values. If you specify a value for `preferredNetwork` at create time, [hideIcon](#elements_create-options-hideIcon) must not be true (so that the Card Brand Choice dropdown can appear) and you cannot specify [payment_method_options.card.network](/js/payment_intents/confirm_card_payment.md#stripe_confirm_card_payment-data-payment_method_options-card-network) at confirm time. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change.md?type=cardElement) changes. - `onNetworksChange` (function) Callback called when the available card networks change. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoadError` (function) Callback called when the Element fails to load. ### Render CardElement ```JSX import React from 'react'; import {Elements, CardElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const CardForm = ({clientSecret}) => ( ); ``` ## CardCvcElement Use the `CardCvcElement` from `@stripe/react-stripe-js` to collect the card's expiration date independently from other card fields. ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Options for creating a `cardCvc` element. - `classes` (object) Set custom class names on the container DOM element when the Stripe element is in a particular state. - `base` (string) The base class applied to the container. Defaults to `StripeElement`. - `complete` (string) The class name to apply when the `Element` is complete. Defaults to `StripeElement--complete`. - `empty` (string) The class name to apply when the `Element` is empty. Defaults to `StripeElement--empty`. - `focus` (string) The class name to apply when the `Element` is focused. Defaults to `StripeElement--focus`. - `invalid` (string) The class name to apply when the `Element` is invalid. Defaults to `StripeElement--invalid`. - `webkitAutofill` (string) The class name to apply when the `Element` has its value autofilled by the browser (only on Chrome and Safari). Defaults to `StripeElement--webkit-autofill`. - `style` (object) Customize the appearance of this element using CSS properties passed in a [Style](/js/appendix/style.md) object. - `placeholder` (string) Customize the placeholder text. - `disabled` (boolean) Applies a disabled state to the Element such that user input is not accepted. Default is `false`. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change.md?type=cardCvcElement) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. ### Render CardCvcElement ```JSX import React from 'react'; import {Elements, CardCvcElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => ( ); ``` ## CardExpiryElement Use the `CardExpiryElement` from `@stripe/react-stripe-js` to collect the card's expiration date independently from other card fields. ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Options for creating a `cardExpiry` element. - `classes` (object) Set custom class names on the container DOM element when the Stripe element is in a particular state. - `base` (string) The base class applied to the container. Defaults to `StripeElement`. - `complete` (string) The class name to apply when the `Element` is complete. Defaults to `StripeElement--complete`. - `empty` (string) The class name to apply when the `Element` is empty. Defaults to `StripeElement--empty`. - `focus` (string) The class name to apply when the `Element` is focused. Defaults to `StripeElement--focus`. - `invalid` (string) The class name to apply when the `Element` is invalid. Defaults to `StripeElement--invalid`. - `webkitAutofill` (string) The class name to apply when the `Element` has its value autofilled by the browser (only on Chrome and Safari). Defaults to `StripeElement--webkit-autofill`. - `style` (object) Customize the appearance of this element using CSS properties passed in a [Style](/js/appendix/style.md) object. - `placeholder` (string) Customize the placeholder text. - `disabled` (boolean) Applies a disabled state to the Element such that user input is not accepted. Default is `false`. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change.md?type=cardExpiryElement) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoadError` (function) Callback called when the Element fails to load. ### Render CardExpiryElement ```JSX import React from 'react'; import {Elements, CardExpiryElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const CardExpiryField = ({clientSecret}) => ( ); ``` ## CardNumberElement Use the `CardNumberElement` from `@stripe/react-stripe-js` to collect the PAN (primary account number) independently while rendering Card CVC and expiration in separate Elements. ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Options for creating a `cardNumber` element. - `classes` (object) Set custom class names on the container DOM element when the Stripe element is in a particular state. - `base` (string) The base class applied to the container. Defaults to `StripeElement`. - `complete` (string) The class name to apply when the `Element` is complete. Defaults to `StripeElement--complete`. - `empty` (string) The class name to apply when the `Element` is empty. Defaults to `StripeElement--empty`. - `focus` (string) The class name to apply when the `Element` is focused. Defaults to `StripeElement--focus`. - `invalid` (string) The class name to apply when the `Element` is invalid. Defaults to `StripeElement--invalid`. - `webkitAutofill` (string) The class name to apply when the `Element` has its value autofilled by the browser (only on Chrome and Safari). Defaults to `StripeElement--webkit-autofill`. - `style` (object) Customize the appearance of this element using CSS properties passed in a [Style](/js/appendix/style.md) object. - `placeholder` (string) Customize the placeholder text. - `disabled` (boolean) Applies a disabled state to the Element such that user input is not accepted. Default is `false`. - `showIcon` (boolean) Show a card brand icon in the Element. Default is `false`. - `iconStyle` (string) Appearance of the icon in the Element. Either `solid` or `default`. - `disableLink` (boolean) Disables and hides the Link button in the Element. Default is `false`. You can also disable Link across all instances of `card` and `cardNumber` elements in your [payment method settings](https://dashboard.stripe.com/settings/payment_methods). - `preferredNetwork` (array) Specifies a network preference for [Card Brand Choice](/card-brand-choice.md). 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](/api/payment_methods/create.md#create_payment_method-card-networks-preferred) for valid values. If you specify a value for `preferredNetwork` at create time, [showIcon](#elements_create-options-showIcon) must be true (so that the Card Brand Choice dropdown can appear) and you cannot specify [payment_method_options.card.network](/js/payment_intents/confirm_card_payment.md#stripe_confirm_card_payment-data-payment_method_options-card-network) at confirm time. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change.md?type=cardNumberElement) changes. - `onNetworksChange` (function) Callback called when the available card networks change. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. - `onLoadError` (function) Callback called when the Element fails to load. ### Render CardNumberElement ```JSX import React from 'react'; import {Elements, CardNumberElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => ( ); ``` ## IbanElement Use the `IbanElement` from `@stripe/react-stripe-js` to collect International Bank Account Numbers (IBANs) for SEPA Direct Debit and similar payment methods. ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) Options for creating an `iban` element. - `classes` (object) Set custom class names on the container DOM element when the Stripe element is in a particular state. - `base` (string) The base class applied to the container. Defaults to `StripeElement`. - `complete` (string) The class name to apply when the `Element` is complete. Defaults to `StripeElement--complete`. - `empty` (string) The class name to apply when the `Element` is empty. Defaults to `StripeElement--empty`. - `focus` (string) The class name to apply when the `Element` is focused. Defaults to `StripeElement--focus`. - `invalid` (string) The class name to apply when the `Element` is invalid. Defaults to `StripeElement--invalid`. - `webkitAutofill` (string) The class name to apply when the `Element` has its value autofilled by the browser (only on Chrome and Safari). Defaults to `StripeElement--webkit-autofill`. - `style` (object) Customize the appearance of this element using CSS properties passed in a [Style](/js/appendix/style.md) object. - `supportedCountries` (array) Specify the list of countries or country-groups whose IBANs you want to allow. Must be `['SEPA']`. - `placeholderCountry` (string) Customize the country and format of the placeholder IBAN. Default is `DE`. - `iconStyle` (string) Appearance of the icon in the Element. Either `solid` or `default`. - `hideIcon` (boolean) Hides the icon in the Element. Default is `false`. - `disabled` (boolean) Applies a disabled state to the Element such that user input is not accepted. Default is `false`. - `onChange` (function) Callback called when any value in the [change event payload](/js/element/events/on_change.md?type=ibanElement) changes. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. - `onEscape` (function) Callback called when the escape key is pressed within the Element. ### Render IbanElement ```JSX import React from 'react'; import {Elements, IbanElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => ( ); ``` ## PaymentRequestButtonElement Use the `PaymentRequestButtonElement` from `@stripe/react-stripe-js` to display Apple Pay, Google Pay, Link, and browser-based payment request buttons powered by the Payment Request API. ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) **required** Options for creating a `paymentRequestButton` element. - `classes` (object) Set custom class names on the container DOM element when the Stripe element is in a particular state. - `base` (string) The base class applied to the container. Defaults to `StripeElement`. - `complete` (string) The class name to apply when the `Element` is complete. Defaults to `StripeElement--complete`. - `empty` (string) The class name to apply when the `Element` is empty. Defaults to `StripeElement--empty`. - `focus` (string) The class name to apply when the `Element` is focused. Defaults to `StripeElement--focus`. - `invalid` (string) The class name to apply when the `Element` is invalid. Defaults to `StripeElement--invalid`. - `webkitAutofill` (string) The class name to apply when the `Element` has its value autofilled by the browser (only on Chrome and Safari). Defaults to `StripeElement--webkit-autofill`. - `style` (object) An object used to customize the appearance of the Payment Request Button. The object must have a single `paymentRequestButton` field, containing any of the following sub-fields: - `type` (string) Preferred button type to display. Available types, by wallet: Browser card: `default`, `book`, `buy`, or `donate`. Google Pay: `default`, `buy`, or `donate`. Apple Pay: `default`, `book`, `buy`, `donate`, `check-out`, `subscribe`, `reload`, `add-money`, `top-up`, `order`, `rent`, `support`, `contribute`, `tip` When a wallet does not support the provided value, `default` is used as a fallback. - `theme` (string) One of `dark`, `light`, or `light-outline`. The default is `dark`. - `height` (string) The height of the Payment Request Button. Accepts `px` unit values. - `paymentRequest` (PaymentRequest) **required** A [PaymentRequest](/js/payment_request.md) object used to configure the element. - `onClick` (function) Callback called when the customer clicks the Element. Receives the [click event payload](/js/element/events/on_click?type=expressCheckoutElement.md#element_on_click-handler). - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. ### Render PaymentRequestButtonElement ```JSX import React, {useMemo} from 'react'; import {Elements, PaymentRequestButtonElement, useStripe} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); const PaymentRequestButton = () => { const stripe = useStripe(); const paymentRequest = useMemo(() => { if (!stripe) { return null; } return stripe.paymentRequest({ country: 'US', currency: 'usd', total: { label: 'Total', amount: 1099, }, }); }, [stripe]); if (!paymentRequest) { return null; } return ( { // Inspect event.paymentRequest for custom analytics or validation. }} /> ); }; export const App = ({clientSecret}) => ( ); ``` ## PaymentMethodMessagingElement Use the `PaymentMethodMessagingElement` from `@stripe/react-stripe-js` to inform a customer about available buy-now-pay-later plans. ### Props - `id` (string) Sets the DOM `id` attribute on the rendered Element container. Use this to target the Element for styling or testing. - `className` (string) Applies custom CSS classes to the Element container. - `options` (object) **required** Options for displaying a `paymentMethodMessaging` element. [See visual examples in the docs.](/payments/payment-method-messaging.md) - `amount` (number) **required** The total amount in the [smallest currency unit](/currencies.md#zero-decimal). - `currency` (string) **required** The currency. One of `AUD`, `CAD`, `CHF`, `CZK`, `DKK`, `EUR`, `GBP`, `NOK`, `NZD`, `PLN`, `RON`, `SEK`, `USD`. - `countryCode` (string) The end-buyer country. One of `AT`, `AU`, `BE`, `CA`, `CH`, `CZ`, `DE`, `DK`, `ES`, `FI`, `FR`, `GB`, `GR`, `IE`, `IT`, `NL`, `NO`, `NZ`, `PL`, `PT`, `RO`, `SE`, `US`. If not set, the buyer's country will be inferred from the request. - `paymentMethodTypes` (array) A list of payment method types to render. You can omit this attribute to manage your payment methods from the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). Any combination of `affirm`, `afterpay_clearpay`, `klarna`. - `paymentMethodOrder` (array) By default, the Payment Method Messaging Element uses a dynamic ordering that optimizes payment method display for each user. You can override the default order in which payment methods display in the Payment Method Messaging Element with a list of payment method types. If there are payment methods that will show that aren't specified in `paymentMethodOrder`, they display after the payment methods you specify. If you specify payment methods that won't show, they are ignored. - `onReady` (function) Callback called once the Element is fully rendered. Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler). - `onBlur` (function) Callback called when the Element loses focus. - `onFocus` (function) Callback called when the Element receives focus. ### Render PaymentMethodMessagingElement ```JSX import React, {useMemo} from 'react'; import {Elements, PaymentMethodMessagingElement} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}'); export const App = ({clientSecret}) => ( ); ```