React Stripe Js

React Stripe.js reference The React bindings for Stripe.js provide context providers, hooks, and Element components for both Checkout Sessions and direct PaymentIntent or SetupIntent integrations. The sections below document the APIs exported from @stripe/react-stripe-js and @the relevant part of the product, grouped by the provider you render (CheckoutElementsProvider or Elements). ## Using the Checkout provider Build your Stripe integration using React, Stripe Elements, and the Checkout Sessions API. See build a checkout page 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. ## CheckoutElementsProvider The CheckoutElementsProvider component allows you to use Element components and access data from your Checkout Session 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 CheckoutElementsProvider, 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 CheckoutElementsProvider along with the client secret of your Checkout Session. ### Props - stripe A Stripe object or a Promise resolving to a Stripe object. The easiest way to initialize a Stripe object is with the Stripe.js wrapper module. After this prop has been set, it can not be changed. - options Options for CheckoutElementsProvider. - clientSecret The Checkout Session client secret or a promise that resolves to the client secret. - elementsOptions A set of options to configure Elements created with Checkout Sessions. - appearance Match the design of your site with the appearance option. The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more. - loader 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 An array of custom fonts that elements created from the Elements object can use. You can specify fonts as CssFontSource or CustomFontSource objects. - savedPaymentMethod Options to configure what Elements displays when used to Save payment details during payment. - enableRedisplay Toggle if Elements redisplays Customer saved Payment Methods. Default is 'auto'. Prior to Clover, this defaulted to 'never'. - enableSave 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 Used with the Address Element. 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. The default value is 'billing'. - adaptivePricing Options for Adaptive Pricing. - allowed Whether Adaptive Pricing can be used with this integration. Default is false. Additional setup is required before you can use Adaptive Pricing with Checkout elements. ### Example title Mount CheckoutElementsProvider ## useCheckoutElements The useCheckoutElements 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 as well as actions to update the Checkout Session. Use useCheckoutElements inside a CheckoutElementsProvider. For CheckoutFormProvider integrations, use useCheckoutForm instead. ### Object properties - id The ID of the Checkout Session. - billingAddress Billing details of the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - businessName The business name as configured in the Business Public Details settings of your Stripe account. - canConfirm 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 Three-letter ISO currency code, in lowercase. Must be a supported currency. - currencyOptions The currency options available on the Checkout Session when using Adaptive Pricing. - amount A formatted string representing the total amount in the source currency, including currency symbols. - minorUnitsAmount An integer representing the total amount in the source currency in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - currencyConversion Currency conversion details. This is only present for the customer currency. - fxRate The exchange rate used to convert source currency amounts to customer currency amounts. - sourceCurrency The creation currency of the Checkout Session before localization. - discountAmounts The aggregate amounts calculated per discount for all line items. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - displayName A user-facing description of the discount. - promotionCode The customer-facing promotion code that was used to apply this discount, if any. - recurring Details of how the discount applies to recurring payments. - type 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 If duration is repeating, the number of months the coupon applies. Null otherwise. - percentOff An integer representing the discount amount as a percentage. - email The Customer's email address. - lastPaymentError The error encountered the last time the Checkout Session was confirmed. - message An error message to be displayed to the customer. - lineItems A list of items the customer is purchasing. - id Unique identifier for the object. - subtotal Total before any discounts or exclusive taxes are applied. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount Total discount amount. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive Total amount of exclusive tax (tax that is collected in addition to the subtotal). - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive Total amount of inclusive tax (tax that is already included in the subtotal). - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total amount for this line item, including discounts and tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - unitAmount The amount representing the cost of a single unit of the item. - amount A formatted string representing the unit amount, including currency symbols. - minorUnitsAmount An integer representing the unit amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - unitAmountDecimal The unit amount of the line item in the smallest currency unit, with sub-cent precision. Use this field instead of unitAmount when dealing with sub-cent pricing (for example, usage-based billing). For sub-cent prices, unitAmount.minorUnitsAmount rounds to 0, so unitAmountDecimal preserves the exact decimal value (for example, 0.005 for a price of 0.00005 USD). - amount A formatted string representing the unit amount with sub-cent precision, including currency symbols. - minorUnitsAmount A number representing the unit amount in the smallest currency unit with sub-cent precision (for example, 0.5 for half a cent). Unlike unitAmount.minorUnitsAmount, this value can be a decimal. - unitLabel A label that represents the unit of this line item. Specify unitLabel in productData.unit_label when creating the Checkout Session or when creating the Product's unit_label field. - description An arbitrary string attached to the object. Often useful for displaying to users. - name The item's name, meant to be displayable to users. - images An array of image URLs for the line item. Specify images on the Product when creating the Checkout Session. - quantity The quantity of products being purchased. - discountAmounts The amount of discount calculated per discount for this line item. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - displayName A user-facing description of the discount. - promotionCode The customer-facing promotion code that was used to apply this discount, if any. - recurring Details of how the discount applies to recurring payments. - type 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 If duration is repeating, the number of months the coupon applies. Null otherwise. - percentOff An integer representing the discount amount as a percentage. - taxAmounts The amount of tax calculated per tax rate for this line item. - amount A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - recurring The recurring components of a price such as interval and intervalCount. - interval Specifies billing frequency. Either day, week, month, or year. - intervalCount The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months. - usageType 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. - adjustableQuantity Configuration for this item's quantity to be adjusted by the customer during checkout. - maximum The maximum quantity the customer can purchase for the Checkout Session. - minimum The minimum quantity the customer can purchase for the Checkout Session. - livemode Has the value true if the object exists in live mode or the value false if the object exists in a sandbox. - minorUnitsAmountDivisor 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. - nameCollection Names collected from the customer. This value is null if name_collection is not configured on the Checkout Session. - individualName The customer's individual name. - businessName The customer's business name. - phoneNumber The Customer's phone number. - recurring Details about recurring payments set up by the Checkout Session. - interval Specifies billing frequency. Either day, week, month, or year. - intervalCount The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months. - dueNext Details about the next scheduled recurring payment. - subtotal Total before any discounts or exclusive taxes are applied. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount Total discount amount. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive Total amount of exclusive tax (tax that is collected in addition to the subtotal). - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive Total amount of inclusive tax (tax that is already included in the subtotal). - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total computed amount, including discounts and tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - billingCycleAnchor 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 Details about a free trial, if there is one. - trialEnd Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. - trialPeriodDays Integer representing the number of trial period days before the customer is charged for the first time. - isProrated When true, the amount to be collected today is a prorated amount for a partial billing period, such as when using billing_cycle_anchor. - savedPaymentMethods An array of payment methods attached to the Customer. - id ID of the PaymentMethod object - type The type of the PaymentMethod - billingDetails Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods. - email Email address. - phone Billing phone number (including extension). - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - card If this is a card PaymentMethod, this hash contains the user's card details. - brand 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 Two-digit number representing the card's expiration month. - expYear Four-digit number representing the card's expiration year. - last4 The last four digits of the card. - shipping The selected shipping option, if any. - shippingOption Details of the selected shipping option. - id Unique identifier for the object. - amount A formatted string representing the shipping amount, including currency symbols. - minorUnitsAmount An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - displayName A user-facing description of the shipping option. - deliveryEstimate The estimated range for how long shipping will take. - maximum The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - minimum The lower bound of the estimated range. If empty, represents no lower bound. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - taxAmounts The amount of tax calculated per tax rate for shipping costs. - amount A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - shippingAddress Shipping address of the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - shippingOptions The list of shipping options that can be selected. - id Unique identifier for the object. - amount A formatted string representing the shipping amount, including currency symbols. - minorUnitsAmount An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - displayName A user-facing description of the shipping option. - deliveryEstimate The estimated range for how long shipping will take. - maximum The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - minimum The lower bound of the estimated range. If empty, represents no lower bound. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - status Status of the Checkout Session. - type 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 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 Details about the tax computation status. - status 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. - automaticTax Details about the automatic tax settings of the Checkout Session. - enabled Whether automatic tax is enabled on the Checkout Session. The other fields in this hash are null when automatic tax is disabled. - exempt One of none, exempt, or reverse. This value is null if automatic tax is disabled, or if the Customer hasn't provided enough address information to determine their tax exemption. * none: The Customer isn't exempt from tax. * exempt: The Customer is exempt from tax. * reverse: The Customer is subject to the reverse charge mechanism, so tax is accounted for by the Customer. - addressSource One of billing, shipping, or customer, indicating which address is used to calculate tax. This value is null if automatic tax is disabled. * billing: Tax is calculated from the billing address collected during this Checkout Session. * shipping: Tax is calculated from the shipping address collected during this Checkout Session. * customer: Tax is calculated from the address saved on the Customer. - taxAmounts 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 A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - total 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 The total amount of line items, excluding tax, discounts, and shipping. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive The sum of all exclusive tax amounts - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive The sum of all inclusive tax amounts - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - shippingRate The sum of all shipping amounts. - amount A formatted string representing the total shipping amount, including currency symbols. - minorUnitsAmount An integer representing the total shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount The sum of all the discounts. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total computed amount, including discounts, tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - appliedBalance Total amount of customer credit balance 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 A formatted string representing the applied customer balance amount, including currency symbols. - minorUnitsAmount An integer representing the applied customer balance amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - balanceAppliedToNextInvoice 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. ### Example title Call useCheckoutElements hook ## useCheckout > This feature is in private preview. See Embedded form for more information. useCheckout is deprecated. Use useCheckoutElements inside a CheckoutElementsProvider, or useCheckoutForm inside a CheckoutFormProvider. The new hooks provide compile-time type safety for the actions available under each provider. 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 as well as actions to update the Checkout Session. ### Object properties - id The ID of the Checkout Session. - billingAddress Billing details of the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - businessName The business name as configured in the Business Public Details settings of your Stripe account. - canConfirm 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 Three-letter ISO currency code, in lowercase. Must be a supported currency. - currencyOptions The currency options available on the Checkout Session when using Adaptive Pricing. - amount A formatted string representing the total amount in the source currency, including currency symbols. - minorUnitsAmount An integer representing the total amount in the source currency in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - currencyConversion Currency conversion details. This is only present for the customer currency. - fxRate The exchange rate used to convert source currency amounts to customer currency amounts. - sourceCurrency The creation currency of the Checkout Session before localization. - discountAmounts The aggregate amounts calculated per discount for all line items. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - displayName A user-facing description of the discount. - promotionCode The customer-facing promotion code that was used to apply this discount, if any. - recurring Details of how the discount applies to recurring payments. - type 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 If duration is repeating, the number of months the coupon applies. Null otherwise. - percentOff An integer representing the discount amount as a percentage. - email The Customer's email address. - lastPaymentError The error encountered the last time the Checkout Session was confirmed. - message An error message to be displayed to the customer. - lineItems A list of items the customer is purchasing. - id Unique identifier for the object. - subtotal Total before any discounts or exclusive taxes are applied. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount Total discount amount. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive Total amount of exclusive tax (tax that is collected in addition to the subtotal). - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive Total amount of inclusive tax (tax that is already included in the subtotal). - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total amount for this line item, including discounts and tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - unitAmount The amount representing the cost of a single unit of the item. - amount A formatted string representing the unit amount, including currency symbols. - minorUnitsAmount An integer representing the unit amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - unitAmountDecimal The unit amount of the line item in the smallest currency unit, with sub-cent precision. Use this field instead of unitAmount when dealing with sub-cent pricing (for example, usage-based billing). For sub-cent prices, unitAmount.minorUnitsAmount rounds to 0, so unitAmountDecimal preserves the exact decimal value (for example, 0.005 for a price of 0.00005 USD). - amount A formatted string representing the unit amount with sub-cent precision, including currency symbols. - minorUnitsAmount A number representing the unit amount in the smallest currency unit with sub-cent precision (for example, 0.5 for half a cent). Unlike unitAmount.minorUnitsAmount, this value can be a decimal. - unitLabel A label that represents the unit of this line item. Specify unitLabel in productData.unit_label when creating the Checkout Session or when creating the Product's unit_label field. - description An arbitrary string attached to the object. Often useful for displaying to users. - name The item's name, meant to be displayable to users. - images An array of image URLs for the line item. Specify images on the Product when creating the Checkout Session. - quantity The quantity of products being purchased. - discountAmounts The amount of discount calculated per discount for this line item. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - displayName A user-facing description of the discount. - promotionCode The customer-facing promotion code that was used to apply this discount, if any. - recurring Details of how the discount applies to recurring payments. - type 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 If duration is repeating, the number of months the coupon applies. Null otherwise. - percentOff An integer representing the discount amount as a percentage. - taxAmounts The amount of tax calculated per tax rate for this line item. - amount A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - recurring The recurring components of a price such as interval and intervalCount. - interval Specifies billing frequency. Either day, week, month, or year. - intervalCount The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months. - usageType 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. - adjustableQuantity Configuration for this item's quantity to be adjusted by the customer during checkout. - maximum The maximum quantity the customer can purchase for the Checkout Session. - minimum The minimum quantity the customer can purchase for the Checkout Session. - livemode Has the value true if the object exists in live mode or the value false if the object exists in a sandbox. - minorUnitsAmountDivisor 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. - nameCollection Names collected from the customer. This value is null if name_collection is not configured on the Checkout Session. - individualName The customer's individual name. - businessName The customer's business name. - phoneNumber The Customer's phone number. - recurring Details about recurring payments set up by the Checkout Session. - interval Specifies billing frequency. Either day, week, month, or year. - intervalCount The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months. - dueNext Details about the next scheduled recurring payment. - subtotal Total before any discounts or exclusive taxes are applied. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount Total discount amount. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive Total amount of exclusive tax (tax that is collected in addition to the subtotal). - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive Total amount of inclusive tax (tax that is already included in the subtotal). - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total computed amount, including discounts and tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - billingCycleAnchor 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 Details about a free trial, if there is one. - trialEnd Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. - trialPeriodDays Integer representing the number of trial period days before the customer is charged for the first time. - isProrated When true, the amount to be collected today is a prorated amount for a partial billing period, such as when using billing_cycle_anchor. - savedPaymentMethods An array of payment methods attached to the Customer. - id ID of the PaymentMethod object - type The type of the PaymentMethod - billingDetails Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods. - email Email address. - phone Billing phone number (including extension). - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - card If this is a card PaymentMethod, this hash contains the user's card details. - brand 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 Two-digit number representing the card's expiration month. - expYear Four-digit number representing the card's expiration year. - last4 The last four digits of the card. - shipping The selected shipping option, if any. - shippingOption Details of the selected shipping option. - id Unique identifier for the object. - amount A formatted string representing the shipping amount, including currency symbols. - minorUnitsAmount An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - displayName A user-facing description of the shipping option. - deliveryEstimate The estimated range for how long shipping will take. - maximum The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - minimum The lower bound of the estimated range. If empty, represents no lower bound. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - taxAmounts The amount of tax calculated per tax rate for shipping costs. - amount A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - shippingAddress Shipping address of the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - shippingOptions The list of shipping options that can be selected. - id Unique identifier for the object. - amount A formatted string representing the shipping amount, including currency symbols. - minorUnitsAmount An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - displayName A user-facing description of the shipping option. - deliveryEstimate The estimated range for how long shipping will take. - maximum The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - minimum The lower bound of the estimated range. If empty, represents no lower bound. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - status Status of the Checkout Session. - type 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 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 Details about the tax computation status. - status 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. - automaticTax Details about the automatic tax settings of the Checkout Session. - enabled Whether automatic tax is enabled on the Checkout Session. The other fields in this hash are null when automatic tax is disabled. - exempt One of none, exempt, or reverse. This value is null if automatic tax is disabled, or if the Customer hasn't provided enough address information to determine their tax exemption. * none: The Customer isn't exempt from tax. * exempt: The Customer is exempt from tax. * reverse: The Customer is subject to the reverse charge mechanism, so tax is accounted for by the Customer. - addressSource One of billing, shipping, or customer, indicating which address is used to calculate tax. This value is null if automatic tax is disabled. * billing: Tax is calculated from the billing address collected during this Checkout Session. * shipping: Tax is calculated from the shipping address collected during this Checkout Session. * customer: Tax is calculated from the address saved on the Customer. - taxAmounts 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 A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - total 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 The total amount of line items, excluding tax, discounts, and shipping. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive The sum of all exclusive tax amounts - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive The sum of all inclusive tax amounts - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - shippingRate The sum of all shipping amounts. - amount A formatted string representing the total shipping amount, including currency symbols. - minorUnitsAmount An integer representing the total shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount The sum of all the discounts. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total computed amount, including discounts, tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - appliedBalance Total amount of customer credit balance 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 A formatted string representing the applied customer balance amount, including currency symbols. - minorUnitsAmount An integer representing the applied customer balance amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - balanceAppliedToNextInvoice 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. ### Example title Call useCheckout hook ## Apply a promotion code applyPromotionCode(promotionCode: string) Use this method to apply a promotion code that your customer enters. - promotionCode The promotion code to apply to the Checkout Session. ### Example title Apply a promotion code ## Remove a promotion code removePromotionCode() Use this method to remove the currently applied promotion code, if applicable. ### Example title Remove a promotion code ## Update the Customer's shipping address updateShippingAddress(shippingAddress: nullable object) Use this method to update the Customer's shipping address. If your integration uses the Express Checkout Element, the shipping address is collected directly from the wallet and the value set by updateShippingAddress is not used for express checkout payments. - shippingAddress New shipping address for the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. ### Example title Update the Customer's shipping address ## Update the Customer's billing address updateBillingAddress(billingAddress: nullable object) Use this method to update the Customer's billing address. If your integration uses the Express Checkout Element, the billing address is collected directly from the wallet and the value set by updateBillingAddress is not used for express checkout payments. - billingAddress New billing information for the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. ### Example title Update the Customer's billing address ## Update the Customer's email address updateEmail(email: nullable string) Use this method to update the Customer's email address. If your integration uses Link 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 (Link is also known as Onelink in the UK). If your integration uses the Express Checkout Element, the email address is collected directly from the wallet and the value set by updateEmail is not used for express checkout payments. - email The Customer's email address. ### Example title Update the Customer's email address ## Update the Customer's phone number updatePhoneNumber(phoneNumber: nullable string) Use this method to update the Customer's phone number. If your integration uses the Express Checkout Element, the phone number is collected directly from the wallet and the value set by updatePhoneNumber is not used for express checkout payments. - phoneNumber The Customer's phone number. ### Example title Update the Customer's phone number ## Update the Customer's business name updateBusinessName(businessName: nullable string) Use this method to update the Customer's business name when name_collection.business.enabled is true on the Checkout Session. If the Tax ID Element is mounted with the business name field shown, calling confirm() throws an IntegrationError because the Tax ID Element collects the business name directly. To use updateBusinessName() instead, set fields.businessName: "never" when creating the Tax ID Element. - businessName The Customer's business name. ### Example title Update the Customer's business name ## Update the Customer's individual name updateIndividualName(individualName: nullable string) Use this method to update the Customer's individual name when name_collection.individual.enabled is true on the Checkout Session. - individualName The Customer's individual name. ### Example title Update the Customer's individual name ## Update the Customer's business name and tax ID updateTaxIdInfo(taxIdInfo?: ) Use this method to update the Customer's business name and tax ID. - taxIdInfo The Customer's tax ID information including the business name and tax ID. - businessName The Customer's business name. - taxId The Customer's tax ID. - type One of the supported tax ID types - value The value of the tax ID. ### Example title Update the Customer's business name and tax ID ## Update line item quantities updateLineItemQuantity(options: object) Use this method to change the quantity of a line item. - options Options for updateLineItemQuantity. - lineItem The ID of the line item to update. - quantity The new quantity of the line item. ### Example title Update line item quantities ## Update the selected shipping option updateShippingOption(shippingOption?: string) Use this method to update the selected shipping option. See shippingOptions for a list of the available shipping options. - shippingOption The ID of the shipping option to select. ### Example title Update the selected shipping option ## Confirm the Checkout Session confirm(options?: object) Use this method to confirm the Checkout Session. You must either read total.total.amount or each of total.total.minorUnitsAmount and currency and 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. - options Options for confirm. - returnUrl 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 The ID of a previously collected PaymentMethod 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 Whether your Customer has provided consent to save the payment method for future purchases. Learn how to save payment methods. - redirect 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 The Customer's email address. If provided, this value overrides any values previously set using updateEmail. - phoneNumber The Customer's phone number. If provided, this value overrides any values previously set using updatePhoneNumber. - billingAddress The Customer's billing address. If provided, this value overrides any values previously set using updateBillingAddress. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - shippingAddress The Customer's shipping address. If provided, this value overrides any values previously set using updateShippingAddress. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - expressCheckoutConfirmEvent The event object passed to your Express Checkout Element confirm handler. - formConfirmEvent The event object passed to your Embedded form confirm handler. ### Example title Confirm the Checkout Session ## Validate Elements validateElements() Use this method to validate all mounted Elements without confirming the Checkout Session. This is useful for multi-step checkout flows where you want to validate user input before advancing to the next step. This method doesn't verify that the Checkout Session can be confirmed. To check whether all required fields are present, use the Session's canConfirm field. ### Example title Validate Elements ## Run server update runServerUpdate(userFunction: function) 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. - userFunction An async function to make a request to your server to update the Checkout Session. ### Example title Run server update ## PaymentElement Use the PaymentElement from @the relevant part of the product to collect payment details for more than 40 payment methods from around the globe. The component must be rendered inside a CheckoutElementsProvider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Payment Element initialization options. - fields By default, the Payment Element collects only the necessary billing details to complete a payment. To collect billing details outside of the Payment Element, use the fields option to disable Payment Element collection of certain fields. You can set billingDetails at the top level to apply the same field collection settings to all payment methods, or set billingDetails under a supported payment method type to override the top-level setting for that payment method. - billingDetails Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto. - name Specify always to require the Payment Element to collect the customer's billing name. - email Specify never to avoid collecting email in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.email=never and walletOptions.emailRequired=true, email is still collected from wallets. - phone Specify never to avoid collecting phone in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.phone=never and walletOptions.phoneNumberRequired=true, phone is still collected from wallets. - address Specify if_required to only collect the minimum billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. Unlike the never option, you don't need to include fields omitted in the Payment Element when confirming the payment. This can reduce the amount of information required to complete the form. Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - postalCode The postal code or ZIP code, also known as PIN code in India. - [paymentMethodType] Optionally specify the billing detail collection settings for any Payment Element payment method type. Examples of valid values are card, klarna, or us_bank_account. You can include one or more payment method type keys. - billingDetails Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto. - name Specify always to require the Payment Element to collect the customer's billing name. - email Specify never to avoid collecting email in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.email=never and walletOptions.emailRequired=true, email is still collected from wallets. - phone Specify never to avoid collecting phone in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.phone=never and walletOptions.phoneNumberRequired=true, phone is still collected from wallets. - address Specify if_required to only collect the minimum billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. Unlike the never option, you don't need to include fields omitted in the Payment Element when confirming the payment. This can reduce the amount of information required to complete the form. Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - postalCode The postal code or ZIP code, also known as PIN code in India. - layout Specify the layout for the Payment Element. If you only pass a layout type ('accordion' or ‘tabs’) without any additional parameters, the Payment Element renders using that layout and the default values associated with it. An object can also be passed to specify the layout with additional configuration. - type Defines the layout to render the Payment Element. - defaultCollapsed Controls if the Payment Element renders in a collapsed state (where no payment method is selected by default). When you leave this undefined, Stripe renders the experience that it determines will have the best conversion. - radios Controls when to render each Payment Method with a radio input next to its logo. The radios visually indicate the current selection of the Payment Element. Defaults to 'auto'. - 'always' — Always show radio inputs. - 'never' — Never show radio inputs. - 'if_multiple' — Show radio inputs only when there are multiple payment methods available. When there is only one payment method, no radio input is displayed. - 'auto' — Stripe determines the best experience to optimize conversion. This property is only applicable to the accordion layout. - spacedAccordionItems When true, the Payment Methods render as standalone buttons with space in between them. This property is only applicable to the accordion layout. - visibleAccordionItemsCount Sets the max number of Payment Methods visible before using the "More" button to hide additional Payment Methods. Set this value to 0 to disable the "More" button and render all available Payment Methods. Default is 5. This property is only applicable to the accordion layout. - paymentMethodLogoPosition Sets the position of the payment method logo in each accordion item. Default is start. This property is only applicable to the accordion layout. - paymentMethodOrder By default, the Payment Element will use a dynamic ordering that optimizes payment method display for each user. You can override the default order in which payment methods are displayed in the Payment Element with a list of payment method types. If the associated 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 Applies a read-only state to the Payment Element so that payment details can’t be changed. Default is false. Enabling the readOnly option doesn't change the Payment Element's visual appearance. If you want to adjust the way the Payment Element looks, use the Appearance API. - terms Control how mandates or other legal agreements are displayed in the Payment Element. Use never to never display legal agreements. The default setting is auto, which causes legal agreements to only be shown when necessary. Consult your legal and compliance advisors before making any changes to the text of mandates or legal agreements. You can't use the terms option to violate obligations under your Stripe agreement, Stripe policies, applicable laws or scheme rules. - applePay - auBecsDebit - bancontact - card - cashapp - googlePay - ideal - paypal - sepaDebit - sofort - usBankAccount - wallets By default, the Payment Element will display all the payment methods that the underlying 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 - googlePay - link - walletOptions Options to control the information collected from the customer when paying with a wallet payment method. - emailRequired Collect the customer's email from wallet payment methods by setting this option to true. - phoneNumberRequired Collect the customer's phone number from wallet payment methods by setting this option to true. PayPal doesn't provide a phone number, even when this option is set to true. Google Pay makes a best effort to return the phone number registered to the wallet, but doesn't guarantee it will be provided in all cases. Link makes a best effort to return the phone number registered to the wallet, but doesn't guarantee it will be provided in all cases. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render PaymentElement ## ExpressCheckoutElement Use the ExpressCheckoutElement from @the relevant part of the product to accept payments through one-click payment buttons. The component must be rendered inside a CheckoutElementsProvider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Express Checkout Element initialization options. - buttonHeight 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 Specify the preferred button theme to use. By default, Elements determines the themes based on the specified appearance option. - applePay - googlePay - paypal - klarna - buttonType Specify the preferred button type to display. - applePay Default is plain. - googlePay Default is buy. - paypal Default is paypal. - klarna Default is pay. - layout 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 Defines the maximum number of columns the Express Checkout Element can use to render. Default is 0, meaning unlimited. - maxRows Defines the maximum number of rows the Express Checkout Element can use to render. Default is 0, meaning unlimited. - overflow 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 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 In addition to your Dashboard configuration, the CheckoutSession configuration also influences the availability of payment methods in the Express Checkout Element. 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 - applePay 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. Apple Pay on non-Safari desktop browsers is only supported when its property in paymentMethods is set to always. - googlePay 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 - paypal - onConfirm Triggered when the Element fires a confirm event. Use this to handle payment confirmation. - onCancel The cancel event is triggered when the payment interface is dismissed (e.g. the customer closes it). 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. The following Checkout Elements support the cancel event: expressCheckoutElement and checkoutForm. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoadError Callback called when the Element fails to load. ### Example title Render ExpressCheckoutElement ## ContactDetailsElement Use the ContactDetailsElement from @the relevant part of the product to collect your customer's email address and help them sign in to Link. The component must be rendered inside a CheckoutElementsProvider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render ContactDetailsElement ## BillingAddressElement Use the BillingAddressElement from @the relevant part of the product to render and update the billing address on the current Checkout Session. The component must be rendered inside a CheckoutElementsProvider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Billing Address Element initialization options. - contacts An array of objects that can be displayed as saved addresses in the Billing Address Element. The first contact is automatically selected. - name The name of the contact. This might be a person, or a business name. - address The address of the contact. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - postal_code The postal code or ZIP code, also known as PIN code in India. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - phone The phone number of the contact. - display You can customize how certain fields are displayed. - name 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. - autocomplete 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 (Link is also known as Onelink in the UK). [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. 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 Specify disabled to disable autocomplete in the Address Element. Specify google_maps_api to enable Google Maps API 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 Specify your own Google Maps API key with it. Only needs to be passed in when autocomplete.mode is set to google_maps_api. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render BillingAddressElement ## ShippingAddressElement Use the ShippingAddressElement from @the relevant part of the product to render and update the shipping address on the current Checkout Session. The component must be rendered inside a CheckoutElementsProvider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Shipping Address Element initialization options. - contacts An array of objects that can be displayed as saved addresses in the Shipping Address Element. The first contact is automatically selected. - name The name of the contact. This might be a person, or a business name. - address The address of the contact. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - postal_code The postal code or ZIP code, also known as PIN code in India. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - phone The phone number of the contact. - display You can customize how certain fields are displayed. - name 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. - autocomplete 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 (Link is also known as Onelink in the UK). [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. 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 Specify disabled to disable autocomplete in the Address Element. Specify google_maps_api to enable Google Maps API 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 Specify your own Google Maps API key with it. Only needs to be passed in when autocomplete.mode is set to google_maps_api. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render ShippingAddressElement ## CurrencySelectorElement Use the CurrencySelectorElement from @the relevant part of the product to allow customers to select the currency for their payment. The component must be rendered inside a CheckoutElementsProvider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render CurrencySelectorElement ## TaxIdElement Use the TaxIdElement from @the relevant part of the product to collect tax ID information from your customers, including business name and tax identification number. The component must be rendered inside a CheckoutElementsProvider. > 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 Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Tax ID Element initialization options. - visibility 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. When name_collection.business.enabled is true on the Checkout Session and visibility is auto, the element displays regardless of the user's country. In countries that do not support tax ID collection, only the business name field shows. - fields 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 Specify always to collect the business name. Specify never to not collect the business name. Default is auto. When name_collection.business.enabled is true on the Checkout Session, setting this to never signals that you are collecting the business name through your own input via updateBusinessName() instead. - validation By default, the Tax ID Element will enforce preset validation for each field. You can customize the settings by using this option. - businessName - required Specify always to make business name a required field. Specify never to make business name an optional field. Default is auto. When name_collection.business.enabled is true on the Checkout Session and name_collection.business.optional is false, the SDK overrides this to always regardless of what you set here. - taxId - required Specify always to make tax ID a required field. Specify never to make tax ID an optional field. Default is auto. - verification Configure real-time tax ID verification. Requires the custom_checkout_tax_id_verification_1 beta. To use it, pass betas: ['custom_checkout_tax_id_1', 'custom_checkout_tax_id_verification_1'] when initializing Stripe.js - taxId - mode Specify if_supported to enable real-time tax ID verification for supported tax ID types. Specify never to disable verification. Default is never. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render TaxIdElement ## Using the Embedded form provider > This feature is in private preview. See Embedded form for more information. Build your Stripe integration using React and the embedded form, a single unified form that bundles payment, address, and other elements. See build an integration with an embedded form for steps on using the embedded form with the Checkout Sessions API. The following React components and hooks are available to use as part of your integration. ## CheckoutFormProvider > This feature is in private preview. See Embedded form for more information. The CheckoutFormProvider component wraps your React tree for the embedded form integration. It initializes the Embedded form SDK and provides it in a context so nested components can render the CheckoutForm component and access session data. To use CheckoutFormProvider, 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 CheckoutFormProvider along with the client secret of your Checkout Session. ### Props - stripe A Stripe object or a Promise resolving to a Stripe object. The easiest way to initialize a Stripe object is with the Stripe.js wrapper module. After this prop has been set, it can not be changed. - options Options for CheckoutFormProvider. - clientSecret The Checkout Session client secret or a promise that resolves to the client secret. - appearance Match the design of your site with the appearance option. The layout stays consistent, but you can modify colors, fonts, borders, padding, and more. Note: the embedded form doesn't support rules. - loader Display skeleton loader UI while waiting for the embedded form to fully load after it's mounted. Default is 'auto' (Stripe determines whether or not to show a loader UI). - fonts An array of custom fonts that the embedded form can use. You can specify fonts as CssFontSource or CustomFontSource objects. - savedPaymentMethod Options to configure what the embedded form displays when used to save payment details during payment. - enableRedisplay Toggle if the embedded form redisplays Customer saved Payment Methods. Default is 'auto'. - enableSave Toggle if the embedded form collects consent to save a customer's payment methods. Default is 'auto'. ### Example title Mount CheckoutFormProvider ## useCheckoutForm > This feature is in private preview. See Embedded form for more information. The useCheckoutForm 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 as well as actions to update the Checkout Session. Use useCheckoutForm inside a CheckoutFormProvider. For CheckoutElementsProvider integrations, use useCheckoutElements instead. ### Object properties - id The ID of the Checkout Session. - billingAddress Billing details of the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - businessName The business name as configured in the Business Public Details settings of your Stripe account. - canConfirm 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 Three-letter ISO currency code, in lowercase. Must be a supported currency. - currencyOptions The currency options available on the Checkout Session when using Adaptive Pricing. - amount A formatted string representing the total amount in the source currency, including currency symbols. - minorUnitsAmount An integer representing the total amount in the source currency in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - currencyConversion Currency conversion details. This is only present for the customer currency. - fxRate The exchange rate used to convert source currency amounts to customer currency amounts. - sourceCurrency The creation currency of the Checkout Session before localization. - discountAmounts The aggregate amounts calculated per discount for all line items. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - displayName A user-facing description of the discount. - promotionCode The customer-facing promotion code that was used to apply this discount, if any. - recurring Details of how the discount applies to recurring payments. - type 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 If duration is repeating, the number of months the coupon applies. Null otherwise. - percentOff An integer representing the discount amount as a percentage. - email The Customer's email address. - lastPaymentError The error encountered the last time the Checkout Session was confirmed. - message An error message to be displayed to the customer. - lineItems A list of items the customer is purchasing. - id Unique identifier for the object. - subtotal Total before any discounts or exclusive taxes are applied. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount Total discount amount. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive Total amount of exclusive tax (tax that is collected in addition to the subtotal). - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive Total amount of inclusive tax (tax that is already included in the subtotal). - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total amount for this line item, including discounts and tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - unitAmount The amount representing the cost of a single unit of the item. - amount A formatted string representing the unit amount, including currency symbols. - minorUnitsAmount An integer representing the unit amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - unitAmountDecimal The unit amount of the line item in the smallest currency unit, with sub-cent precision. Use this field instead of unitAmount when dealing with sub-cent pricing (for example, usage-based billing). For sub-cent prices, unitAmount.minorUnitsAmount rounds to 0, so unitAmountDecimal preserves the exact decimal value (for example, 0.005 for a price of 0.00005 USD). - amount A formatted string representing the unit amount with sub-cent precision, including currency symbols. - minorUnitsAmount A number representing the unit amount in the smallest currency unit with sub-cent precision (for example, 0.5 for half a cent). Unlike unitAmount.minorUnitsAmount, this value can be a decimal. - unitLabel A label that represents the unit of this line item. Specify unitLabel in productData.unit_label when creating the Checkout Session or when creating the Product's unit_label field. - description An arbitrary string attached to the object. Often useful for displaying to users. - name The item's name, meant to be displayable to users. - images An array of image URLs for the line item. Specify images on the Product when creating the Checkout Session. - quantity The quantity of products being purchased. - discountAmounts The amount of discount calculated per discount for this line item. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - displayName A user-facing description of the discount. - promotionCode The customer-facing promotion code that was used to apply this discount, if any. - recurring Details of how the discount applies to recurring payments. - type 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 If duration is repeating, the number of months the coupon applies. Null otherwise. - percentOff An integer representing the discount amount as a percentage. - taxAmounts The amount of tax calculated per tax rate for this line item. - amount A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - recurring The recurring components of a price such as interval and intervalCount. - interval Specifies billing frequency. Either day, week, month, or year. - intervalCount The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months. - usageType 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. - adjustableQuantity Configuration for this item's quantity to be adjusted by the customer during checkout. - maximum The maximum quantity the customer can purchase for the Checkout Session. - minimum The minimum quantity the customer can purchase for the Checkout Session. - livemode Has the value true if the object exists in live mode or the value false if the object exists in a sandbox. - minorUnitsAmountDivisor 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. - nameCollection Names collected from the customer. This value is null if name_collection is not configured on the Checkout Session. - individualName The customer's individual name. - businessName The customer's business name. - phoneNumber The Customer's phone number. - recurring Details about recurring payments set up by the Checkout Session. - interval Specifies billing frequency. Either day, week, month, or year. - intervalCount The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months. - dueNext Details about the next scheduled recurring payment. - subtotal Total before any discounts or exclusive taxes are applied. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount Total discount amount. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive Total amount of exclusive tax (tax that is collected in addition to the subtotal). - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive Total amount of inclusive tax (tax that is already included in the subtotal). - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total computed amount, including discounts and tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - billingCycleAnchor 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 Details about a free trial, if there is one. - trialEnd Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. - trialPeriodDays Integer representing the number of trial period days before the customer is charged for the first time. - isProrated When true, the amount to be collected today is a prorated amount for a partial billing period, such as when using billing_cycle_anchor. - savedPaymentMethods An array of payment methods attached to the Customer. - id ID of the PaymentMethod object - type The type of the PaymentMethod - billingDetails Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods. - email Email address. - phone Billing phone number (including extension). - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - card If this is a card PaymentMethod, this hash contains the user's card details. - brand 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 Two-digit number representing the card's expiration month. - expYear Four-digit number representing the card's expiration year. - last4 The last four digits of the card. - shipping The selected shipping option, if any. - shippingOption Details of the selected shipping option. - id Unique identifier for the object. - amount A formatted string representing the shipping amount, including currency symbols. - minorUnitsAmount An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - displayName A user-facing description of the shipping option. - deliveryEstimate The estimated range for how long shipping will take. - maximum The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - minimum The lower bound of the estimated range. If empty, represents no lower bound. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - taxAmounts The amount of tax calculated per tax rate for shipping costs. - amount A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - shippingAddress Shipping address of the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - shippingOptions The list of shipping options that can be selected. - id Unique identifier for the object. - amount A formatted string representing the shipping amount, including currency symbols. - minorUnitsAmount An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - displayName A user-facing description of the shipping option. - deliveryEstimate The estimated range for how long shipping will take. - maximum The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - minimum The lower bound of the estimated range. If empty, represents no lower bound. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - status Status of the Checkout Session. - type 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 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 Details about the tax computation status. - status 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. - automaticTax Details about the automatic tax settings of the Checkout Session. - enabled Whether automatic tax is enabled on the Checkout Session. The other fields in this hash are null when automatic tax is disabled. - exempt One of none, exempt, or reverse. This value is null if automatic tax is disabled, or if the Customer hasn't provided enough address information to determine their tax exemption. * none: The Customer isn't exempt from tax. * exempt: The Customer is exempt from tax. * reverse: The Customer is subject to the reverse charge mechanism, so tax is accounted for by the Customer. - addressSource One of billing, shipping, or customer, indicating which address is used to calculate tax. This value is null if automatic tax is disabled. * billing: Tax is calculated from the billing address collected during this Checkout Session. * shipping: Tax is calculated from the shipping address collected during this Checkout Session. * customer: Tax is calculated from the address saved on the Customer. - taxAmounts 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 A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - total 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 The total amount of line items, excluding tax, discounts, and shipping. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive The sum of all exclusive tax amounts - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive The sum of all inclusive tax amounts - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - shippingRate The sum of all shipping amounts. - amount A formatted string representing the total shipping amount, including currency symbols. - minorUnitsAmount An integer representing the total shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount The sum of all the discounts. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total computed amount, including discounts, tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - appliedBalance Total amount of customer credit balance 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 A formatted string representing the applied customer balance amount, including currency symbols. - minorUnitsAmount An integer representing the applied customer balance amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - balanceAppliedToNextInvoice 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. ### Example title Call useCheckoutForm hook ## useCheckout > This feature is in private preview. See Embedded form for more information. useCheckout is deprecated. Use useCheckoutElements inside a CheckoutElementsProvider, or useCheckoutForm inside a CheckoutFormProvider. The new hooks provide compile-time type safety for the actions available under each provider. 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 as well as actions to update the Checkout Session. ### Object properties - id The ID of the Checkout Session. - billingAddress Billing details of the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - businessName The business name as configured in the Business Public Details settings of your Stripe account. - canConfirm 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 Three-letter ISO currency code, in lowercase. Must be a supported currency. - currencyOptions The currency options available on the Checkout Session when using Adaptive Pricing. - amount A formatted string representing the total amount in the source currency, including currency symbols. - minorUnitsAmount An integer representing the total amount in the source currency in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - currencyConversion Currency conversion details. This is only present for the customer currency. - fxRate The exchange rate used to convert source currency amounts to customer currency amounts. - sourceCurrency The creation currency of the Checkout Session before localization. - discountAmounts The aggregate amounts calculated per discount for all line items. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - displayName A user-facing description of the discount. - promotionCode The customer-facing promotion code that was used to apply this discount, if any. - recurring Details of how the discount applies to recurring payments. - type 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 If duration is repeating, the number of months the coupon applies. Null otherwise. - percentOff An integer representing the discount amount as a percentage. - email The Customer's email address. - lastPaymentError The error encountered the last time the Checkout Session was confirmed. - message An error message to be displayed to the customer. - lineItems A list of items the customer is purchasing. - id Unique identifier for the object. - subtotal Total before any discounts or exclusive taxes are applied. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount Total discount amount. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive Total amount of exclusive tax (tax that is collected in addition to the subtotal). - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive Total amount of inclusive tax (tax that is already included in the subtotal). - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total amount for this line item, including discounts and tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - unitAmount The amount representing the cost of a single unit of the item. - amount A formatted string representing the unit amount, including currency symbols. - minorUnitsAmount An integer representing the unit amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - unitAmountDecimal The unit amount of the line item in the smallest currency unit, with sub-cent precision. Use this field instead of unitAmount when dealing with sub-cent pricing (for example, usage-based billing). For sub-cent prices, unitAmount.minorUnitsAmount rounds to 0, so unitAmountDecimal preserves the exact decimal value (for example, 0.005 for a price of 0.00005 USD). - amount A formatted string representing the unit amount with sub-cent precision, including currency symbols. - minorUnitsAmount A number representing the unit amount in the smallest currency unit with sub-cent precision (for example, 0.5 for half a cent). Unlike unitAmount.minorUnitsAmount, this value can be a decimal. - unitLabel A label that represents the unit of this line item. Specify unitLabel in productData.unit_label when creating the Checkout Session or when creating the Product's unit_label field. - description An arbitrary string attached to the object. Often useful for displaying to users. - name The item's name, meant to be displayable to users. - images An array of image URLs for the line item. Specify images on the Product when creating the Checkout Session. - quantity The quantity of products being purchased. - discountAmounts The amount of discount calculated per discount for this line item. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - displayName A user-facing description of the discount. - promotionCode The customer-facing promotion code that was used to apply this discount, if any. - recurring Details of how the discount applies to recurring payments. - type 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 If duration is repeating, the number of months the coupon applies. Null otherwise. - percentOff An integer representing the discount amount as a percentage. - taxAmounts The amount of tax calculated per tax rate for this line item. - amount A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - recurring The recurring components of a price such as interval and intervalCount. - interval Specifies billing frequency. Either day, week, month, or year. - intervalCount The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months. - usageType 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. - adjustableQuantity Configuration for this item's quantity to be adjusted by the customer during checkout. - maximum The maximum quantity the customer can purchase for the Checkout Session. - minimum The minimum quantity the customer can purchase for the Checkout Session. - livemode Has the value true if the object exists in live mode or the value false if the object exists in a sandbox. - minorUnitsAmountDivisor 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. - nameCollection Names collected from the customer. This value is null if name_collection is not configured on the Checkout Session. - individualName The customer's individual name. - businessName The customer's business name. - phoneNumber The Customer's phone number. - recurring Details about recurring payments set up by the Checkout Session. - interval Specifies billing frequency. Either day, week, month, or year. - intervalCount The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months. - dueNext Details about the next scheduled recurring payment. - subtotal Total before any discounts or exclusive taxes are applied. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount Total discount amount. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive Total amount of exclusive tax (tax that is collected in addition to the subtotal). - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive Total amount of inclusive tax (tax that is already included in the subtotal). - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total computed amount, including discounts and tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - billingCycleAnchor 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 Details about a free trial, if there is one. - trialEnd Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. - trialPeriodDays Integer representing the number of trial period days before the customer is charged for the first time. - isProrated When true, the amount to be collected today is a prorated amount for a partial billing period, such as when using billing_cycle_anchor. - savedPaymentMethods An array of payment methods attached to the Customer. - id ID of the PaymentMethod object - type The type of the PaymentMethod - billingDetails Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods. - email Email address. - phone Billing phone number (including extension). - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - card If this is a card PaymentMethod, this hash contains the user's card details. - brand 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 Two-digit number representing the card's expiration month. - expYear Four-digit number representing the card's expiration year. - last4 The last four digits of the card. - shipping The selected shipping option, if any. - shippingOption Details of the selected shipping option. - id Unique identifier for the object. - amount A formatted string representing the shipping amount, including currency symbols. - minorUnitsAmount An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - displayName A user-facing description of the shipping option. - deliveryEstimate The estimated range for how long shipping will take. - maximum The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - minimum The lower bound of the estimated range. If empty, represents no lower bound. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - taxAmounts The amount of tax calculated per tax rate for shipping costs. - amount A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - shippingAddress Shipping address of the Customer. - name Full name. - address Address. - country Two-letter country code (ISO 3166-1 alpha-2). - line1 Address line 1 (e.g., street, PO Box, or company name). - line2 Address line 2 (e.g., apartment, suite, unit, or building). - city City, district, suburb, town, or village. - postal_code ZIP or postal code. - state State, county, province, or region. - shippingOptions The list of shipping options that can be selected. - id Unique identifier for the object. - amount A formatted string representing the shipping amount, including currency symbols. - minorUnitsAmount An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - currency Three-letter ISO currency code, in lowercase. - displayName A user-facing description of the shipping option. - deliveryEstimate The estimated range for how long shipping will take. - maximum The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - minimum The lower bound of the estimated range. If empty, represents no lower bound. - unit A unit of time. Either business_day, day, hour, week, or month. - value Must be greater than 0. - status Status of the Checkout Session. - type 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 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 Details about the tax computation status. - status 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. - automaticTax Details about the automatic tax settings of the Checkout Session. - enabled Whether automatic tax is enabled on the Checkout Session. The other fields in this hash are null when automatic tax is disabled. - exempt One of none, exempt, or reverse. This value is null if automatic tax is disabled, or if the Customer hasn't provided enough address information to determine their tax exemption. * none: The Customer isn't exempt from tax. * exempt: The Customer is exempt from tax. * reverse: The Customer is subject to the reverse charge mechanism, so tax is accounted for by the Customer. - addressSource One of billing, shipping, or customer, indicating which address is used to calculate tax. This value is null if automatic tax is disabled. * billing: Tax is calculated from the billing address collected during this Checkout Session. * shipping: Tax is calculated from the shipping address collected during this Checkout Session. * customer: Tax is calculated from the address saved on the Customer. - taxAmounts 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 A formatted string representing the tax amount, including currency symbols. - minorUnitsAmount An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - inclusive Whether this tax amount is inclusive or exclusive. - displayName A user-facing description of the tax. - percentage The tax rate percentage. This value is absent for flat-amount tax rates. - total 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 The total amount of line items, excluding tax, discounts, and shipping. - amount A formatted string representing the subtotal amount, including currency symbols. - minorUnitsAmount An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxExclusive The sum of all exclusive tax amounts - amount A formatted string representing the exclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - taxInclusive The sum of all inclusive tax amounts - amount A formatted string representing the inclusive tax amount, including currency symbols. - minorUnitsAmount An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - shippingRate The sum of all shipping amounts. - amount A formatted string representing the total shipping amount, including currency symbols. - minorUnitsAmount An integer representing the total shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - discount The sum of all the discounts. A positive number reduces the amount to be paid. - amount A formatted string representing the discount amount, including currency symbols. - minorUnitsAmount An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - total Total computed amount, including discounts, tax. - amount A formatted string representing the total amount, including currency symbols. - minorUnitsAmount An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - appliedBalance Total amount of customer credit balance 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 A formatted string representing the applied customer balance amount, including currency symbols. - minorUnitsAmount An integer representing the applied customer balance amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). - balanceAppliedToNextInvoice 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. ### Example title Call useCheckout hook ## CheckoutForm > This feature is in private preview. See Embedded form for more information. Use the CheckoutForm from @the relevant part of the product to render the embedded form; a single form that handles payment, address, and other elements. The component must be rendered inside a CheckoutFormProvider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Embedded form initialization options. - layout The layout of the embedded form. The 'expanded' layout is a single-step embedded form, while the 'compact' layout is a multi-step embedded form. When you leave this undefined, Stripe renders the layout it determines has the best conversion. - contacts An array of objects that you can use to display saved addresses in the embedded form. The first contact is automatically selected. - name The name of the contact. This might be a person, or a business name. - address The address of the contact. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - postal_code The postal code or ZIP code, also known as PIN code in India. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - phone The phone number of the contact. - features Configuration for client-side features of the embedded form. Use this to disable default features of the Checkout Session that you prefer to implement in your own UI instead. - promotionCodeCollection Controls whether to show promotion code input in the embedded form. Defaults to 'auto'. - 'auto': Shows the promotion code input if the Checkout Session enables allow_promotion_codes. - 'never': Never shows the promotion code input in the embedded form. Use this if you build your own promotion code input outside of the form. - expressCheckout Express checkout configuration options. - buttonHeight 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 Specify the preferred button theme to use. By default, Elements determines the themes based on the specified appearance option. - applePay - googlePay - paypal - klarna - paymentMethods In addition to your Dashboard configuration, the CheckoutSession configuration also influences the availability of payment methods in the Embedded form. By default, it displays all available payment methods based on both configurations. When setting the paymentMethods option, the Embedded form merges your specified options with the default logic to determine the final set of payment methods displayed. - amazonPay - applePay 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. Apple Pay on non-Safari desktop browsers is only supported when its property in paymentMethods is set to always. - googlePay 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 - paypal - onChange Callback called when any value in the change event payload changes. - onConfirm Triggered when the embedded form sends a confirm event. Use this to handle payment confirmation. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoadError Callback called when the Element fails to load. ### Example title Render CheckoutForm ## Using the Elements provider Build your Stripe integration using React and Stripe Elements. See build a checkout page for steps on using Elements with the Payment Intents API. 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, see the ElementsProvider without an intent reference instead. ### Props - stripe A Stripe object or a Promise that resolves to one. The value returned from loadStripe is the recommended way to initialize this prop. - options A set of options to create this Elements instance with. - fonts An array of custom fonts, which elements created from the Elements object can use. Fonts can be specified as CssFontSource or CustomFontSource objects. - locale A locale 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 Required to use with the Payment Element and the Contact Details Element. The client secret for a PaymentIntent or SetupIntent. - appearance Supported for the Payment Element, the Contact Details Element, and the Address Element. Match the design of your site with the appearance option. The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more. - loader Supported for the Payment Element, the Contact Details Element, and the Address Element. 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 Used with the Payment Element. Influences available payment methods when creating SetupIntents with automatic_payment_methods. Payment Element renders the payment methods enabled in the Stripe Dashboard that support the provided currency. Three-letter ISO currency code, in lowercase. Must be a supported currency. - customerSessionClientSecret Used with the Payment Element and Address Element. The client_secret returned from create a CustomerSession associated with the Customer ID for that session. - syncAddressCheckbox Used with the Address Element. 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 Used with the Payment Element and Express Checkout Element. Allows PaymentMethods to be created from the Elements instance using stripe.createPaymentMethod. NOTE: The Express Checkout Element doesn't support stripe.createPaymentMethod with Amazon Pay or Klarna. Use stripe.createConfirmationToken instead. Card installments are also unsupported and either blocks showing the plan selection UI, or raises an error for manual enablement using paymentMethodOptions. - customPaymentMethods Supported for the Payment Element and Express Checkout Element. An array of custom payment methods to display in the Payment Element or Express Checkout Element. The custom payment methods must be registered in the Stripe Dashboard. - id The ID of the custom payment method type, prefixed with cpmt_. - options A set of options that configure the custom payment method. options and payment are mutually exclusive. - type The form type of the custom payment method. - subtitle A subtitle contains additional information about the custom payment method. - payment A set of options that configure the custom payment method in the Payment Element. This is an alias of options. payment and options are mutually exclusive. - type The form type of the custom payment method. - subtitle A subtitle contains additional information about the custom payment method. - externalPaymentMethodTypes (deprecated) This param has been deprecated in favor of custom payment methods, which offers more flexibility. The external payment methods to be displayed in the Payment Element that you are already integrated with. Must be an available external payment methods. - children Elements renders its children once the Stripe object and Elements instance are ready. ### Example title Mount Elements ## 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, and Card Elements. For other elements, see the ElementsProvider reference instead. ### Props - stripe A Stripe object or a Promise that resolves to one. The value returned from loadStripe is the recommended way to initialize this prop. - options A set of options to create this Elements instance with. - fonts An array of custom fonts, which elements created from the Elements object can use. Fonts can be specified as CssFontSource or CustomFontSource objects. - locale A locale 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 Required to use with the Payment Element and Express Checkout Element. Filters out payment methods based on intended use. - currency Required to use with the Payment Element and Express Checkout Element. Three-letter ISO currency code, in lowercase. Must be a supported currency. - amount Used with the Payment Element and Express Checkout Element. 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 (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. 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 Used with the Payment Element and Express Checkout Element. Indicates that you intend to make future payments with the payment details collected by the Payment Element. This should match the setup_future_usage provided on the Intent used when confirming payment. - captureMethod Used with the Payment Element and Express Checkout Element. Influences available payment methods. This should match the capture_method provided on the Intent used when confirming payment. - onBehalfOf Used with the Payment Element, Express Checkout Element, and Card Elements. The Stripe account ID which is the business of record. See use cases to determine if this option is relevant for your integration. This should match the on_behalf_of provided on the Intent used when confirming payment. - paymentMethodTypes Used with the Payment Element and Express Checkout Element. A list of payment method types to render. You can omit this attribute to manage your payment methods from the Stripe Dashboard. - paymentMethodConfiguration Used with the Payment Element and Express Checkout Element. The payment method configuration to use when managing your payment methods from the Stripe Dashboard. If none is specified, your default configuration is used. - paymentMethodOptions Used with the Payment Element and Express Checkout Element. Additional payment-method-specific options for configuring behavior when initialized without an intent. - acss_debit If this is an acss_debit PaymentMethod, this sub-hash contains details about the the related setting Debit payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - affirm If this is an affirm PaymentMethod, this sub-hash contains details about the Affirm payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is an afterpay_clearpay PaymentMethod, this sub-hash contains details about the Afterpay / Clearpay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is an alipay PaymentMethod, this sub-hash contains details about the Alipay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - amazon_pay If this is an amazon_pay PaymentMethod, this sub-hash contains details about the Amazon Pay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - au_becs_debit If this is an au_becs_debit PaymentMethod, this sub-hash contains details about the the related setting Debit payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - bacs_debit If this is a bacs_debit PaymentMethod, this sub-hash contains details about the Bacs Debit payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - bancontact If this is a bancontact PaymentMethod, this sub-hash contains details about the Bancontact payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - blik If this is a blik PaymentMethod, this sub-hash contains details about the the related setting payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a boleto PaymentMethod, this sub-hash contains details about the Boleto payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - card If this is a card PaymentMethod, this sub-hash contains details about the card payment method options. - require_cvc_recollection 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 Installment configuration. - enabled 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. You must set mode='payment' and explicitly specify allowedPaymentMethodTypes in the Elements options. Setting installments to true without these settings returns an error. Incompatible with paymentMethodCreation='manual'. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - cashapp If this is a cashapp PaymentMethod, this sub-hash contains details about the Cash App Pay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - crypto If this is a crypto PaymentMethod, this sub-hash contains details about the Crypto payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a customer_balance PaymentMethod, this sub-hash contains details about the Customer Balance payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is an eps PaymentMethod, this sub-hash contains details about the EPS payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is an fpx PaymentMethod, this sub-hash contains details about the FPX payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a giropay PaymentMethod, this sub-hash contains details about the giropay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a grabpay PaymentMethod, this sub-hash contains details about the GrabPay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is an ideal PaymentMethod, this sub-hash contains details about the iDEAL payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - kakao_pay If this is a kakao_pay PaymentMethod, this sub-hash contains details about the Kakao Pay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - klarna If this is a klarna PaymentMethod, this sub-hash contains details about the Klarna payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - konbini If this is a konbini PaymentMethod, this sub-hash contains details about the Konbini payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a kr_card PaymentMethod, this sub-hash contains details about the Korean card payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - link If this is a link PaymentMethod, this sub-hash contains details about the Link payment method options (Link is also known as Onelink in the UK). - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - mb_way If this is a mb_way PaymentMethod, this sub-hash contains details about the MB WAY payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a mobilepay PaymentMethod, this sub-hash contains details about the MobilePay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a multibanco PaymentMethod, this sub-hash contains details about the Multibanco payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a naver_pay PaymentMethod, this sub-hash contains details about the Naver Pay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - nz_bank_account 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 Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - oxxo If this is an oxxo PaymentMethod, this sub-hash contains details about the the related setting payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a p24 PaymentMethod, this sub-hash contains details about the Przelewy24 payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a paynow PaymentMethod, this sub-hash contains details about the PayNow payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a pix PaymentMethod, this sub-hash contains details about the Pix payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a paypal PaymentMethod, this sub-hash contains details about the PayPal payment method options. - capture_method Controls when the funds will be captured. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - promptpay If this is a promptpay PaymentMethod, this sub-hash contains details about the PromptPay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a revolut_pay PaymentMethod, this sub-hash contains details about the Revolut Pay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - satispay If this is a satispay PaymentMethod, this sub-hash contains details about the Satispay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - sepa_debit If this is a sepa_debit PaymentMethod, this sub-hash contains details about the the related setting Debit payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - sequra If this is a sequra PaymentMethod, this sub-hash contains details about the SeQura payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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. - sofort If this is a sofort PaymentMethod, this sub-hash contains details about the Sofort payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - sunbit If this is a sunbit PaymentMethod, this sub-hash contains details about the Sunbit payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a swish PaymentMethod, this sub-hash contains details about the Swish payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a twint PaymentMethod, this sub-hash contains details about the the related setting payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a upi PaymentMethod, this sub-hash contains details about the UPI payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - us_bank_account If this is a us_bank_account PaymentMethod, this sub-hash contains details about the US bank account payment method options. - verification_method Verification method for the US bank account collection flow - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Use off_session if your customer may or may not be present in your checkout flow. - on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. - financial_connections Additional fields for Financial Connections session creation - permissions 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 The list of permissions that you would like to retrieve upon creation. Valid permissions include: balances, ownership, and transactions. - wechat_pay If this is a wechat_pay PaymentMethod, this sub-hash contains details about the WeChat Pay payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 If this is a zip PaymentMethod, this sub-hash contains details about the Zip payment method options. - setup_future_usage Indicates that you intend to make future payments with the payment details collected by the Payment Element. - none 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 Supported for the Payment Element, the Contact Details Element, the Express Checkout Element, and the Address Element. Match the design of your site with the appearance option. The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more. - loader Supported for the Payment Element, the Contact Details Element, and the Address Element. 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 Used with the Payment Element and Address Element. The client_secret returned from create a CustomerSession associated with the Customer ID for that session. - syncAddressCheckbox Used with the Address Element. 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 Used with the Payment Element and Express Checkout Element. Allows PaymentMethods to be created from the Elements instance using stripe.createPaymentMethod. NOTE: The Express Checkout Element doesn't support stripe.createPaymentMethod with Amazon Pay or Klarna. Use stripe.createConfirmationToken instead. Card installments are also unsupported and either blocks showing the plan selection UI, or raises an error for manual enablement using paymentMethodOptions. - allowedPaymentMethodTypes Used with the Payment Element and Express Checkout Element. The list of payment method types to allow for this payment. From this list, Stripe automatically renders the relevant payment methods. You can omit this attribute to manage your payment methods from the Stripe Dashboard. - excludedPaymentMethodTypes Used with the Payment Element and Express Checkout Element. The list of payment method types to exclude from use with this payment. - customPaymentMethods Supported for the Payment Element and Express Checkout Element. An array of custom payment methods to display in the Payment Element or Express Checkout Element. The custom payment methods must be registered in the Stripe Dashboard. - id The ID of the custom payment method type, prefixed with cpmt_. - options A set of options that configure the custom payment method. options and payment are mutually exclusive. - type The form type of the custom payment method. - subtitle A subtitle contains additional information about the custom payment method. - payment A set of options that configure the custom payment method in the Payment Element. This is an alias of options. payment and options are mutually exclusive. - type The form type of the custom payment method. - subtitle A subtitle contains additional information about the custom payment method. - children Elements renders its children once the Stripe object and Elements instance are ready. ### Example title Mount Elements ## useStripe hook The useStripe hook returns the initialized Stripe.js instance from the Elements provider. Use it to confirm payments 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 instead. ### Return value - result Returns the Stripe instance configured on the provider, or null while it is still loading. ### Example title Call useStripe ## 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 instead. ### Return value - result Returns the current Elements instance or null while the provider is still loading. ### Example title Call useElements ## ElementsConsumer ElementsConsumer exposes the same Stripe and Elements instances as the hooks, 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 A render prop that receives {stripe, elements}. Render your UI using these instances. ### Example title Render ElementsConsumer ## PaymentElement Use the PaymentElement from @stripe/react-stripe-js to collect payment details for more than 40 payment methods from around the globe. The component must be rendered inside an Elements Provider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating the Payment Element. - layout Specify the layout for the Payment Element. If you only pass a layout type ('accordion' or ‘tabs’) without any additional parameters, the Payment Element renders using that layout and the default values associated with it. An object can also be passed to specify the layout with additional configuration. - type Defines the layout to render the Payment Element. - defaultCollapsed Controls if the Payment Element renders in a collapsed state (where no payment method is selected by default). When you leave this undefined, Stripe renders the experience that it determines will have the best conversion. - radios Controls when to render each Payment Method with a radio input next to its logo. The radios visually indicate the current selection of the Payment Element. Defaults to 'auto'. - 'always' — Always show radio inputs. - 'never' — Never show radio inputs. - 'if_multiple' — Show radio inputs only when there are multiple payment methods available. When there is only one payment method, no radio input is displayed. - 'auto' — Stripe determines the best experience to optimize conversion. This property is only applicable to the accordion layout. - spacedAccordionItems When true, the Payment Methods render as standalone buttons with space in between them. This property is only applicable to the accordion layout. - visibleAccordionItemsCount Sets the max number of Payment Methods visible before using the "More" button to hide additional Payment Methods. Set this value to 0 to disable the "More" button and render all available Payment Methods. Default is 5. This property is only applicable to the accordion layout. - paymentMethodLogoPosition Sets the position of the payment method logo in each accordion item. Default is start. This property is only applicable to the accordion layout. - defaultValues Provide initial customer information that will be displayed in the Payment Element. The form will render with empty fields if not provided. - billingDetails Specify customer's billing details, which lets you pre-fill a customer’s name, email, phone number and address if required by payment method. Pre-filling as much information as possible streamlines the checkout process. - name - email - phone - address - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - postal_code The postal code or ZIP code, also known as PIN code in India. - paymentMethods Specify customer's default information for different payment methods. Pre-filling as much information as possible streamlines the checkout process. - ideal - bank A pre-filled iDEAL bank value for the Payment Element. Can only be one of the banks listed in the iDEAL guide (e.g., abn_amro). - payto - usePayId When true, the PayTo payment method will default to showing the PayID input instead of BSB/account number fields. Customers can still switch between PayID and BSB/account number using the toggle link. - card Specify default settings for card payments. - network Specifies a network preference for Card Brand Choice. The first network in the array that matches a network on the entered co-branded card will be selected by default in the Card Brand Choice dropdown. See the supported networks for valid values. - business Provide information about your business that will be displayed in the Payment Element. This information will be retrieved from your Stripe account if not provided. - name The name of your business. Your business name will be used to render mandate text for some payment methods. - paymentMethodOrder By default, the Payment Element will use a dynamic ordering that optimizes payment method display for each user. You can override the default order in which payment methods are displayed in the Payment Element with a list of payment method types. If the associated PaymentIntent has payment method types not specified in paymentMethodOrder, they will be displayed after the payment methods you specify. If you specify payment method types not on the associated PaymentIntent, they will be ignored. - fields By default, the Payment Element collects all necessary details to complete a payment. For some payment methods, the Payment Element collects details such as name or email that you might have already collected from the customer. If this is the case, you can prevent the Payment Element from collecting these details by using the fields option. If you disable collecting certain fields with the fields option, you must pass that same data to stripe.confirmPayment or we'll reject the payment. You can set billingDetails at the top level to apply the same field collection settings to all payment methods, or set billingDetails under a supported payment method type to override the top-level setting for that payment method. Learn how to customize the billing details to collect and the customized fields. - billingDetails Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto. - name Specify always to require the Payment Element to collect the customer's billing name. - email Specify never to avoid collecting email in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.email=never and walletOptions.emailRequired=true, email is still collected from wallets. - phone Specify never to avoid collecting phone in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.phone=never and walletOptions.phoneNumberRequired=true, phone is still collected from wallets. - address Specify if_required to only collect the minimum billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. Unlike the never option, you don't need to include fields omitted in the Payment Element when confirming the payment. This can reduce the amount of information required to complete the form. Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - postalCode The postal code or ZIP code, also known as PIN code in India. - [paymentMethodType] Optionally specify the billing detail collection settings for any Payment Element payment method type. Examples of valid values are card, klarna, or us_bank_account. You can include one or more payment method type keys. - billingDetails Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto. - name Specify always to require the Payment Element to collect the customer's billing name. - email Specify never to avoid collecting email in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.email=never and walletOptions.emailRequired=true, email is still collected from wallets. - phone Specify never to avoid collecting phone in the Payment Element. Note that this parameter is independent of walletOptions, so if you set fields.billingDetails.phone=never and walletOptions.phoneNumberRequired=true, phone is still collected from wallets. - address Specify if_required to only collect the minimum billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. Unlike the never option, you don't need to include fields omitted in the Payment Element when confirming the payment. This can reduce the amount of information required to complete the form. Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - postalCode The postal code or ZIP code, also known as PIN code in India. - readOnly Applies a read-only state to the Payment Element so that payment details can’t be changed. Default is false. Enabling the readOnly option doesn't change the Payment Element's visual appearance. If you want to adjust the way the Payment Element looks, use the Appearance API. - terms Control how mandates or other legal agreements are displayed in the Payment Element. Use never to never display legal agreements. The default setting is auto, which causes legal agreements to only be shown when necessary. Consult your legal and compliance advisors before making any changes to the text of mandates or legal agreements. You can't use the terms option to violate obligations under your Stripe agreement, Stripe policies, applicable laws or scheme rules. - applePay - auBecsDebit - bancontact - card - cashapp - googlePay - ideal - paypal - sepaDebit - sofort - usBankAccount - wallets By default, the Payment Element will display all the payment methods that the underlying Payment Intent was created with. However, wallets like Apple Pay and Google Pay are not payment methods per the Payment Intent API. They will show when the Payment Intent has the card payment method and the customer is using a supported platform and have an active card in their account. This is the auto behavior, and it is the default for choice for all wallets. If you do not want to show a given wallet as a payment option, you can set its property in wallets to never. - applePay - googlePay - link - walletOptions Options to control the information collected from the customer when paying with a wallet payment method. - emailRequired Collect the customer's email from wallet payment methods by setting this option to true. - phoneNumberRequired Collect the customer's phone number from wallet payment methods by setting this option to true. PayPal doesn't provide a phone number, even when this option is set to true. Google Pay makes a best effort to return the phone number registered to the wallet, but doesn't guarantee it will be provided in all cases. Link makes a best effort to return the phone number registered to the wallet, but doesn't guarantee it will be provided in all cases. - applePay Specify Apple Pay specific options. These are passed through to the Apple Pay API. - recurringPaymentRequest Specify a request to set up a recurring payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - regularBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - trialBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - billingAgreement - deferredPaymentRequest Specify a request to set up a deferred payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - deferredBilling - amount - amountType Indicates whether the billing amount is known at request time. When set to 'final', the Apple Pay payment sheet shows the configured amount. - label - deferredPaymentDate - billingAgreement - freeCancellationDate If set, you must also supply a freeCancellationDateTimeZone., - freeCancellationDateTimeZone "If set, you must also supply a freeCancellationDate., - automaticReloadPaymentRequest Specify a request to set up an automatic reload payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - automaticReloadBilling - amount - label - automaticReloadPaymentThresholdAmount - billingAgreement - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render PaymentElement ## 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. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating the Express Checkout Element. - allowedShippingCountries 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 Specify Apple Pay specific options. These are passed through to the Apple Pay API. - recurringPaymentRequest Specify a request to set up a recurring payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - regularBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - trialBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - billingAgreement - deferredPaymentRequest Specify a request to set up a deferred payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - deferredBilling - amount - amountType Indicates whether the billing amount is known at request time. When set to 'final', the Apple Pay payment sheet shows the configured amount. - label - deferredPaymentDate - billingAgreement - freeCancellationDate If set, you must also supply a freeCancellationDateTimeZone. - freeCancellationDateTimeZone If set, you must also supply a freeCancellationDate. These are tz timezones such as America/Los_Angeles, Europe/Dublin, and Asia/Singapore. - automaticReloadPaymentRequest Specify a request to set up an automatic reload payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - automaticReloadBilling - amount - label - automaticReloadPaymentThresholdAmount - billingAgreement - billingAddressRequired 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 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 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 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 Specify the preferred button theme to use. By default, Elements determines the themes based on the specified appearance option. - applePay - googlePay - paypal - klarna - buttonType Specify the preferred button type to display. - applePay Default is plain. - googlePay Default is buy. - paypal Default is paypal. - klarna Default is pay. - emailRequired Collect the customer's email by setting this option to true. - layout 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 Defines the maximum number of columns the Express Checkout Element can use to render. Default is 0, meaning unlimited. - maxRows Defines the maximum number of rows the Express Checkout Element can use to render. Default is 0, meaning unlimited. - overflow 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 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 The name of the line item surfaced to the customer in the payment interface. - amount The amount in the currency's subunit (for example, cents, yen, etc.). - paymentMethods 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 - applePay 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 non-Safari desktop browsers is only supported when its property in paymentMethods is set to always. - googlePay 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 - paypal - klarna - paymentMethodOrder 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 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 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 An array of ShippingRate objects. The first shipping rate listed appears in the payment interface as the default option. - id Unique identifier for the object. - amount The amount to charge for shipping. - displayName The name of the shipping rate, displayed to the customer in the payment interface. - deliveryEstimate 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 The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite). - unit A unit of time. - value Must be greater than 0. - minimum The lower bound of the estimated range. If empty, it represents no lower bound. - unit A unit of time. - value Must be greater than 0. - onConfirm The confirm event is triggered from an Express Checkout Element when the customer finalizes their payment. - onClick The click event is triggered from an Express Checkout Element when the customer clicks a payment button. - onCancel 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 Triggered when a customer changes their shipping address. - onShippingRateChange Triggered when a customer changes their shipping rate. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoadError Callback called when the Element fails to load. ### Example title Render ExpressCheckoutElement ## 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. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating the Address Element. - mode Specify which mode you would like to use Address Element for. When shipping mode is used with the Payment Element and Contact Details 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 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 (Link is also known as Onelink in the UK). [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. 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 Specify disabled to disable autocomplete in the Address Element. Specify google_maps_api to enable Google Maps API 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 Specify your own Google Maps API key with it. Only needs to be passed in when autocomplete.mode is set to google_maps_api. - allowedCountries 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 By default, PO boxes are considered a valid address type. You can override this to invalidate PO Boxes. - contacts An array of objects that can be displayed as saved addresses in the Address Element. The first contact will be automatically selected. If using a CustomerSession, Address Element will ignore contacts and render saved billing addresses instead. - name The name of the contact. This might be a person, or a business name. - address The address of the contact. - line1 - line2 - city The name of a city, town, village, etc. - state The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - postal_code The postal code or ZIP code, also known as PIN code in India. - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - phone The phone number of the contact. The fields.phone option must be set to always if this property is specified. - defaultValues Provide the initial information that will be displayed in the Address Element. The form will render with empty fields if not provided. - name Provide the initial full name or organization name. - firstName Provide the initial first name. The display.name option must be set to split if this property is specified. - lastName Provide the initial last name. The display.name option must be set to split if this property is specified. - phone Provide the initial phone number value. The fields.phone option must be set to always if this property is specified. - address Provide the initial address details. - line1 - line2 - city - state - postal_code - country - fields 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 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 By default, the Address Element will enforce preset validation for each field. You can customize the settings by using this option. - phone - required Specify always to make phone number a required field. The fields.phone option must be set to always if this property is specified. Default is auto. - display You can customize how certain fields are displayed. - name 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 Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render AddressElement ## ContactDetailsElement Use the ContactDetailsElement from @stripe/react-stripe-js to collect email addresses and allow users to log into Link on your checkout page. This element was previously known as the Link Authentication Element. The component must be rendered inside an Elements Provider. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating the Contact Details Element. - defaultValues Provide the initial contact information that will be displayed in the Contact Details Element. The form will render with empty fields if not provided. - email - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render ContactDetailsElement ## 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. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Tax ID Element initialization options. - visibility 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 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 Specify always to collect the business name. Specify never to not collect the business name. Default is auto. - validation By default, the Tax ID Element will enforce preset validation for each field. You can customize the settings by using this option. - businessName - required Specify always to make business name a required field. Specify never to make business name an optional field. Default is auto. - taxId - required Specify always to make tax ID a required field. Specify never to make tax ID an optional field. Default is auto. - verification Configure real-time tax ID verification. Requires the elements_tax_id_verification_1 beta. To use it, pass betas: ['elements_tax_id_1', 'elements_tax_id_verification_1'] when initializing Stripe.js - taxId - mode Specify if_supported to enable real-time tax ID verification for supported tax ID types. Specify never to disable verification. Default is never. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoaderStart Callback called right before Stripe displays the Element skeleton loader. Receives the Element instance as its only argument. - onLoadError Callback called when the Element fails to load. ### Example title Render TaxIdElement ## 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 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 the related setting Direct Debit payments. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating an auBankAccount element. - classes Set custom class names on the container DOM element when the Stripe element is in a particular state. - base The base class applied to the container. Defaults to StripeElement. - complete The class name to apply when the Element is complete. Defaults to StripeElement--complete. - empty The class name to apply when the Element is empty. Defaults to StripeElement--empty. - focus The class name to apply when the Element is focused. Defaults to StripeElement--focus. - invalid The class name to apply when the Element is invalid. Defaults to StripeElement--invalid. - webkitAutofill 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 Customize the appearance of this element using CSS properties passed in a Style object. - iconStyle Appearance of the icon in the Element. Either solid or default. - hideIcon Hides the icon in the Element. Default is false. - disabled Applies a disabled state to the Element such that user input is not accepted. Default is false. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. ### Example title Render AuBankAccountElement ## CardElement Use the CardElement from @stripe/react-stripe-js to collect card details with automatic validation. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating a card element. - classes Set custom class names on the container DOM element when the Stripe element is in a particular state. - base The base class applied to the container. Defaults to StripeElement. - complete The class name to apply when the Element is complete. Defaults to StripeElement--complete. - empty The class name to apply when the Element is empty. Defaults to StripeElement--empty. - focus The class name to apply when the Element is focused. Defaults to StripeElement--focus. - invalid The class name to apply when the Element is invalid. Defaults to StripeElement--invalid. - webkitAutofill 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 Customize the appearance of this element using CSS properties passed in a Style object. - value 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 - hidePostalCode 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 Appearance of the icon in the Element. Either solid or default. - hideIcon Hides the icon in the Element. Default is false. - disabled Applies a disabled state to the Element such that user input is not accepted. Default is false. - disableLink 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. - preferredNetwork Specifies a network preference for Card Brand Choice. The first network in the array that matches a network on the entered co-branded card will be selected by default in the Card Brand Choice dropdown. See the supported networks for valid values. If you specify a value for preferredNetwork at create time, hideIcon must not be true (so that the Card Brand Choice dropdown can appear) and you cannot specify payment_method_options.card.network at confirm time. - onChange Callback called when any value in the change event payload changes. - onNetworksChange Callback called when the available card networks change. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoadError Callback called when the Element fails to load. ### Example title Render CardElement ## CardCvcElement Use the CardCvcElement from @stripe/react-stripe-js to collect the card's expiration date independently from other card fields. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating a cardCvc element. - classes Set custom class names on the container DOM element when the Stripe element is in a particular state. - base The base class applied to the container. Defaults to StripeElement. - complete The class name to apply when the Element is complete. Defaults to StripeElement--complete. - empty The class name to apply when the Element is empty. Defaults to StripeElement--empty. - focus The class name to apply when the Element is focused. Defaults to StripeElement--focus. - invalid The class name to apply when the Element is invalid. Defaults to StripeElement--invalid. - webkitAutofill 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 Customize the appearance of this element using CSS properties passed in a Style object. - placeholder Customize the placeholder text. - disabled Applies a disabled state to the Element such that user input is not accepted. Default is false. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. ### Example title Render CardCvcElement ## CardExpiryElement Use the CardExpiryElement from @stripe/react-stripe-js to collect the card's expiration date independently from other card fields. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating a cardExpiry element. - classes Set custom class names on the container DOM element when the Stripe element is in a particular state. - base The base class applied to the container. Defaults to StripeElement. - complete The class name to apply when the Element is complete. Defaults to StripeElement--complete. - empty The class name to apply when the Element is empty. Defaults to StripeElement--empty. - focus The class name to apply when the Element is focused. Defaults to StripeElement--focus. - invalid The class name to apply when the Element is invalid. Defaults to StripeElement--invalid. - webkitAutofill 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 Customize the appearance of this element using CSS properties passed in a Style object. - placeholder Customize the placeholder text. - disabled Applies a disabled state to the Element such that user input is not accepted. Default is false. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoadError Callback called when the Element fails to load. ### Example title Render CardExpiryElement ## 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 Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating a cardNumber element. - classes Set custom class names on the container DOM element when the Stripe element is in a particular state. - base The base class applied to the container. Defaults to StripeElement. - complete The class name to apply when the Element is complete. Defaults to StripeElement--complete. - empty The class name to apply when the Element is empty. Defaults to StripeElement--empty. - focus The class name to apply when the Element is focused. Defaults to StripeElement--focus. - invalid The class name to apply when the Element is invalid. Defaults to StripeElement--invalid. - webkitAutofill 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 Customize the appearance of this element using CSS properties passed in a Style object. - placeholder Customize the placeholder text. - disabled Applies a disabled state to the Element such that user input is not accepted. Default is false. - showIcon Show a card brand icon in the Element. Default is false. - iconStyle Appearance of the icon in the Element. Either solid or default. - disableLink 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. - preferredNetwork Specifies a network preference for Card Brand Choice. The first network in the array that matches a network on the entered co-branded card will be selected by default in the Card Brand Choice dropdown. See the supported networks for valid values. If you specify a value for preferredNetwork at create time, showIcon must be true (so that the Card Brand Choice dropdown can appear) and you cannot specify payment_method_options.card.network at confirm time. - onChange Callback called when any value in the change event payload changes. - onNetworksChange Callback called when the available card networks change. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. - onLoadError Callback called when the Element fails to load. ### Example title Render CardNumberElement ## IbanElement Use the IbanElement from @stripe/react-stripe-js to collect International Bank Account Numbers (IBANs) for the related setting Direct Debit and similar payment methods. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for creating an iban element. - classes Set custom class names on the container DOM element when the Stripe element is in a particular state. - base The base class applied to the container. Defaults to StripeElement. - complete The class name to apply when the Element is complete. Defaults to StripeElement--complete. - empty The class name to apply when the Element is empty. Defaults to StripeElement--empty. - focus The class name to apply when the Element is focused. Defaults to StripeElement--focus. - invalid The class name to apply when the Element is invalid. Defaults to StripeElement--invalid. - webkitAutofill 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 Customize the appearance of this element using CSS properties passed in a Style object. - supportedCountries Specify the list of countries or country-groups whose IBANs you want to allow. Must be ['the related setting']. - placeholderCountry Customize the country and format of the placeholder the related setting. Default is DE. - iconStyle Appearance of the icon in the Element. Either solid or default. - hideIcon Hides the icon in the Element. Default is false. - disabled Applies a disabled state to the Element such that user input is not accepted. Default is false. - onChange Callback called when any value in the change event payload changes. - onReady Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. - onEscape Callback called when the escape key is pressed within the Element. ### Example title Render IbanElement ## PaymentMethodMessagingElement Use the PaymentMethodMessagingElement from @stripe/react-stripe-js to inform a customer about available buy-now-pay-later plans. ### Props - id Sets the DOM id attribute on the rendered Element container. Use this to target the Element for styling or testing. - className Applies custom CSS classes to the Element container. - options Options for displaying a paymentMethodMessaging element. See visual examples in the docs. - amount The total amount in the smallest currency unit. - currency The currency. One of AUD, CAD, CHF, CZK, DKK, EUR, GBP, NOK, NZD, PLN, RON, SEK, USD. - countryCode 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 A list of payment method types to render. You can omit this attribute to manage your payment methods from the Stripe Dashboard. Any combination of affirm, afterpay_clearpay, klarna. - paymentMethodOrder 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 Callback called once the Element is fully rendered. Recieves the ready event payload. - onBlur Callback called when the Element loses focus. - onFocus Callback called when the Element receives focus. ### Example title Render PaymentMethodMessagingElement