Elements with the Checkout Sessions API Build an online checkout page 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 Stripe.js methods are available to use as part of your integration. ## Initialize the Checkout Elements SDK stripe.initCheckoutElementsSdk(options?: object) This method initializes Checkout for Checkout elements integrations, where you compose individual Elements on your checkout page. - options Checkout initialization options. - 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. - 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. - defaultValues If customer details are already known, this option may be passed to prefill the Checkout Session and related elements. - billingAddress The Customer's billing address. - 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. - 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. - email The Customer's email address. - phoneNumber The Customer's phone number. ### Example title Initialize the Checkout Elements SDK ## Initialize the Embedded form SDK stripe.initCheckoutFormSdk(options?: object) > This feature is in private preview. See Embedded form for more information. This method initializes Checkout for embedded form integrations, where a single form handles payment, address, and other elements. - options Embedded form SDK initialization options. - 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: rules are not supported in the embedded form. - 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'. - defaultValues If customer details are already known, you can pass this option to prefill the Checkout Session and the embedded form. - billingAddress The Customer's billing address. - 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. - 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. - email The Customer's email address. - phoneNumber The Customer's phone number. ### Example title Initialize the Embedded form SDK ## Checkout actions checkout.loadActions() After calling initCheckoutElementsSdk, use loadActions() to access methods for reading and manipulating Checkout Sessions. ### Example title Checkout actions ## Read session data actions.getSession() This method returns an object that contains data about the Checkout Session. ### Example title Read session data ## Apply a promotion code actions.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 actions.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 actions.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 actions.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 actions.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 actions.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 actions.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 actions.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 actions.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 actions.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 actions.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 ## Validate Elements actions.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 ## Confirm the Checkout Session actions.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 ## Run server update actions.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 ## The Session object The Session object is a view of the Checkout Session API object and represents your customer's session on your checkout page. Because data can change over the lifecycle of a session, avoid storing a reference to the Session object. Instead, call getSession to retrieve the current value, or listen to the change event to subscribe to updates. - 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. ## Checkout events Listen to Checkout events to respond to changes caused by customer actions on your checkout page. ## Change event checkout.on(event: 'change', handler: function) The change event is triggered when Checkout Session data changes, such as when the customer changes their shipping address. The event payload is always a Checkout Session object. - event The name of the event. In this case, change. - handlerhandler(session) => void is a callback function that you provide that will be called when the event is fired. When called it will be passed a Checkout Session object. ### Example title Listen to change events ## Use Elements with the Checkout Sessions API Stripe Elements are customizable UI components you can use to build your checkout page. Use the Checkout Elements SDK instance to create and manage Elements. ## Create a Payment Element checkout.createPaymentElement(options?: object) This method creates an instance of a Payment Element. - 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. ### Example title Create a Payment Element ## Create a Billing Address Element checkout.createBillingAddressElement(options?: object) This method creates an instance of a Billing Address Element. - 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. ### Example title Create a Billing Address Element ## Create a Shipping Address Element checkout.createShippingAddressElement(options?: object) This method creates an instance of a Shipping Address Element. - 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. ### Example title Create a Shipping Address Element ## Create an Express Checkout Element checkout.createExpressCheckoutElement(options?: object) This method creates an instance of an Express Checkout Element. - 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 ### Example title Create an Express Checkout Element ## Create a Currency Selector Element checkout.createCurrencySelectorElement() This method creates an instance of a Currency Selector Element. ### Example title Create a Currency Selector Element ## Create a Tax ID Element checkout.createTaxIdElement(options?: object) This method creates an instance of a Tax ID Element. > This feature requires the custom_checkout_tax_id_1 beta. To use it, pass betas: ['custom_checkout_tax_id_1'] when initializing Stripe.js. - 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. ### Example title Create a Tax ID Element ## Create a Contact Details Element checkout.createContactDetailsElement() This method creates an instance of a Contact Details Element, which collects your customer's email address and helps them sign in to Link. ### Example title Create a Contact Details Element ## Get the Payment Element checkout.getPaymentElement() This method gets the previously created Payment Element instance, if it exists. ### Example title Get the Payment Element ## Get the Contact Details Element checkout.getContactDetailsElement() This method gets the previously created Contact Details Element instance, if it exists. ### Example title Get the Contact Details Element ## Get the Billing Address Element checkout.getBillingAddressElement() This method gets the previously created Billing Address Element instance, if it exists. ### Example title Get the Billing Address Element ## Get value from a Billing Address Element element.getValue(options?: object) Validates and retrieves form values from a Billing Address Element. If there are any input validation errors, the errors will display by their respective fields. - options An optional options object to control the format of the returned values. - format Controls the format of the state field in the returned address value. * latin: Return the state in Latin characters (for example, "Tokyo"). * localized: Return the state in the locale's native script (for example, "東京"). If unspecified in Stripe.js Clover and below, format is determined by a heuristic based on the customer's browser language. If unspecified in Stripe.js Dahlia and above, defaults to latin. ### Example title Get value from a Billing Address Element ## Get the Shipping Address Element checkout.getShippingAddressElement() This method gets the previously created Shipping Address Element instance, if it exists. ### Example title Get the Shipping Address Element ## Get value from a Shipping Address Element element.getValue(options?: object) Validates and retrieves form values from a Shipping Address Element. If there are any input validation errors, the errors will display by their respective fields. - options An optional options object to control the format of the returned values. - format Controls the format of the state field in the returned address value. * latin: Return the state in Latin characters (for example, "Tokyo"). * localized: Return the state in the locale's native script (for example, "東京"). If unspecified in Stripe.js Clover and below, format is determined by a heuristic based on the customer's browser language. If unspecified in Stripe.js Dahlia and above, defaults to latin. ### Example title Get value from a Shipping Address Element ## Get the Express Checkout Element checkout.getExpressCheckoutElement() This method gets the previously created Express Checkout Element instance, if it exists. ### Example title Get the Express Checkout Address Element ## Get the Currency Selector Element checkout.getCurrencySelectorElement() This method gets the previously created Currency Selector Element instance, if it exists. ### Example title Get the Currency Selector Address Element ## Change the visual customization of Elements using the Appearance API checkout.changeAppearance(appearance: object) Change the visual customization of Elements created with Custom Checkout using the Appearance API - 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. ### Example title Change the visual customization of Elements ## Load additional custom fonts into Elements checkout.loadFonts(fonts: array) Load an additional array of custom fonts into Elements after it loads. - fonts An array of custom fonts. Specify fonts as CssFontSource or CustomFontSource objects. ### Example title Load additional custom fonts ## Embedded form methods > This feature is in private preview. See Embedded form for more information. Use the Embedded form SDK instance to create and manage the embedded form. ## Create an embedded form checkoutFormSdk.createForm(options?: object) > This feature is in private preview. See Embedded form for more information. This method creates an instance of an embedded form. Call initCheckoutFormSdk first to obtain the checkoutFormSdk object. - 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 ### Example title Create an embedded form ## Create a Currency Selector Element checkoutFormSdk.createCurrencySelectorElement() > This feature is in private preview. See Embedded form for more information. This method creates an instance of a Currency Selector Element. The checkoutFormSdk object is obtained by calling initCheckoutFormSdk. ### Example title Create a Currency Selector Element ## Get the embedded form checkoutFormSdk.getForm() > This feature is in private preview. See Embedded form for more information. This method gets the previously created embedded form instance, if it exists. You can obtain the checkoutFormSdk by calling initCheckoutFormSdk. ### Example title Get the embedded form ## Get the Currency Selector Element checkoutFormSdk.getCurrencySelectorElement() > This feature is in private preview. See Embedded form for more information. This method gets the previously created Currency Selector Element instance, if it exists. The checkoutFormSdk object is obtained by calling initCheckoutFormSdk. ### Example title Get the Currency Selector Element ## Set the view on the embedded form checkoutForm.setView(viewIndex: number) > This feature is in private preview. See Embedded form for more information. Programmatically sets the active view on the embedded form. This method is only available when options[layout] is 'compact'. The viewIndex parameter is a positive integer that corresponds to an index from the views array provided on the embedded form's change event. You can only set a view where enabled is true. - viewIndex A positive integer index corresponding to an entry in the views array provided on the embedded form's change event. The view at the specified index must have enabled: true. ### Example title Set the view on the embedded form ## Listen to Elements events Communicate with your Element by listening to an event. An Element might emit any of the events below. All events have a payload object that has an elementType property with the type of the Element that emitted the event. Use the .on method on the Element instance to listen to events. See also: Elements methods | Listen to Checkout events ## Change event element.on(event: 'change', handler: function) The change event is triggered when any value in the change event payload changes. The event payload always contains certain keys, in addition to some Element-specific keys. The following Checkout Elements support the change event: paymentElement, billingAddressElement, shippingAddressElement, taxIdElement, and checkoutForm. > Consult with your legal counsel regarding your requirements and obligations about how you collect, use, and store customers' personal data ## Ready event element.on(event: 'ready', handler: function) Triggered when the Element is fully rendered and methods on the instance, like element.focus() and element.update(), can be called. - event The name of the event. In this case, ready. - handlerhandler(event) => void is a callback function that you provide that will be called when the event is fired. After it's called, it passes an event object with the following properties: - elementType The type of element the event is fired from. ### Example title Handle an Element ready event ## Focus event element.on(event: 'focus', handler: function) Triggered when the Element gains focus. - event The name of the event. In this case, focus. - handlerhandler(event) => void is a callback function that you provide that will be called when the event is fired. ### Example title Handle an Element focus event ## Blur event element.on(event: 'blur', handler: function) Triggered when the Element loses focus. - event The name of the event. In this case, blur. - handlerhandler(event) => void is a callback function that you provide that will be called when the event is fired. ### Example title Handle an Element blur event ## Escape event element.on(event: 'escape', handler: function) Triggered when the escape key is pressed within an Element. - event The name of the event. In this case, escape. - handlerhandler(event) => void is a callback function that you provide that will be called when the event is fired. ### Example title Handle an Element escape event ## LoadError event element.on(event: 'loaderror', handler: function) Triggered when the Element fails to load. - event The name of the event. In this case, loaderror. - handlerhandler(event) => void is a callback function that you provide that will be called when the event is fired. When called it will be passed an event object with the following properties: - elementType The type of element that emitted this event. - error An error object that describes the failure. ### Example title Handle an Element loaderror event ## LoaderStart event element.on(event: 'loaderstart', handler: function) Triggered when the loader UI is mounted to the DOM and ready to be displayed. See also: Elements methods | Listen to Elements events - event The name of the event. In this case, loaderstart. - handlerhandler(event) => void is a callback function that you provide that will be called when the event is fired. When called it will be passed an event object with the following properties: - elementType The type of element that emitted this event. ### Example title Handle a Checkout Element loaderstart event ## Confirm event element.on(event: string, handler: function) The confirm event is triggered when the customer finalizes their payment. Use this event to trigger payment confirmation. The following Checkout Elements support the confirm event: expressCheckoutElement and checkoutForm. ## Cancel event element.on(event: string, handler: function) 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.
