Interface EmbeddedPaymentElementConfiguration

Configuration object (subset of EmbeddedPaymentElement.Configuration).

interface EmbeddedPaymentElementConfiguration {
    merchantDisplayName: string;
    customerId?: string;
    customerEphemeralKeySecret?: string;
    customerSessionClientSecret?: string;
    applePay?: PaymentSheet.ApplePayParams;
    googlePay?: PaymentSheet.GooglePayParams;
    link?: PaymentSheet.LinkParams;
    style?: UserInterfaceStyle;
    returnURL?: string;
    billingDetailsCollectionConfiguration?: PaymentSheet.BillingDetailsCollectionConfiguration;
    defaultBillingDetails?: BillingDetails;
    defaultShippingDetails?: AddressDetails;
    allowsDelayedPaymentMethods?: boolean;
    appearance?: RecursivePartial<
        {
            font: PaymentSheet.FontConfig;
            colors: | PaymentSheet.GlobalColorConfig
            | {
                light: PaymentSheet.GlobalColorConfig;
                dark: PaymentSheet.GlobalColorConfig;
            };
            shapes: {
                borderRadius: number;
                borderWidth: number;
                shadow: PaymentSheet.ShadowConfig;
            };
            primaryButton: PaymentSheet.PrimaryButtonConfig;
            embeddedPaymentElement: PaymentSheet.EmbeddedPaymentElementAppearance;
            formInsetValues: PaymentSheet.EdgeInsetsConfig;
            applyLiquidGlass?: boolean;
            navigationBarStyle?: PaymentSheet.NavigationBarStyle;
        },
    >;
    primaryButtonLabel?: string;
    removeSavedPaymentMethodMessage?: string;
    preferredNetworks?: CardBrand[];
    paymentMethodOrder?: String[];
    allowsRemovalOfLastSavedPaymentMethod?: boolean;
    cardBrandAcceptance?: PaymentSheet.CardBrandAcceptance;
    formSheetAction?: EmbeddedFormSheetAction;
    customPaymentMethodConfiguration?: PaymentSheet.CustomPaymentMethodConfiguration;
    rowSelectionBehavior?: EmbeddedRowSelectionBehavior;
    embeddedViewDisplaysMandateText?: boolean;
}

Properties

merchantDisplayName customerId? customerEphemeralKeySecret? customerSessionClientSecret? applePay? googlePay? link? style? returnURL? billingDetailsCollectionConfiguration? defaultBillingDetails? defaultShippingDetails? allowsDelayedPaymentMethods? appearance? primaryButtonLabel? removeSavedPaymentMethodMessage? preferredNetworks? paymentMethodOrder? allowsRemovalOfLastSavedPaymentMethod? cardBrandAcceptance? formSheetAction? customPaymentMethodConfiguration? rowSelectionBehavior? embeddedViewDisplaysMandateText?

Properties

merchantDisplayName

merchantDisplayName: string

Your customer-facing business name. On Android, this is required and cannot be an empty string.

OptionalcustomerId

customerId?: string

The identifier of the Stripe Customer object. See https://stripe.com/docs/api/customers/object#customer_object-id

OptionalcustomerEphemeralKeySecret

customerEphemeralKeySecret?: string

A short-lived token that allows the SDK to access a Customer's payment methods.

OptionalcustomerSessionClientSecret

customerSessionClientSecret?: string

The client secret of this Customer Session. Used on the client to set up secure access to the given customer.

OptionalapplePay

applePay?: PaymentSheet.ApplePayParams

iOS only. Enable Apple Pay in the Payment Sheet by passing an ApplePayParams object.

OptionalgooglePay

googlePay?: PaymentSheet.GooglePayParams

Android only. Enable Google Pay in the Payment Sheet by passing a GooglePayParams object.

Optionallink

link?: PaymentSheet.LinkParams

Configuration for Link

Optionalstyle

style?: UserInterfaceStyle

The color styling to use for PaymentSheet UI. Defaults to 'automatic'.

OptionalreturnURL

returnURL?: string

A URL that redirects back to your app that EmbeddedPaymentElement can use to auto-dismiss web views used for additional authentication, e.g. 3DS2

OptionalbillingDetailsCollectionConfiguration

billingDetailsCollectionConfiguration?: PaymentSheet.BillingDetailsCollectionConfiguration

Configuration for how billing details are collected during checkout.

OptionaldefaultBillingDetails

defaultBillingDetails?: BillingDetails

PaymentSheet pre-populates the billing fields that are displayed in the Payment Sheet (only country and postal code, as of this version) with these values, if provided.

OptionaldefaultShippingDetails

defaultShippingDetails?: AddressDetails

The shipping information for the customer. If set, EmbeddedPaymentElement will pre-populate the form fields with the values provided. This is used to display a "Billing address is same as shipping" checkbox if defaultBillingDetails is not provided. If name and line1 are populated, it's also attached to the PaymentIntent during payment.

OptionalallowsDelayedPaymentMethods

allowsDelayedPaymentMethods?: boolean

If true, allows payment methods that do not move money at the end of the checkout. Defaults to false.

Some payment methods can’t guarantee you will receive funds from your customer at the end of the checkout because they take time to settle (eg. most bank debits, like SEPA or ACH) or require customer action to complete (e.g. OXXO, Konbini, Boleto). If this is set to true, make sure your integration listens to webhooks for notifications on whether a payment has succeeded or not.

Optionalappearance

appearance?: RecursivePartial<
    {
        font: PaymentSheet.FontConfig;
        colors: | PaymentSheet.GlobalColorConfig
        | {
            light: PaymentSheet.GlobalColorConfig;
            dark: PaymentSheet.GlobalColorConfig;
        };
        shapes: {
            borderRadius: number;
            borderWidth: number;
            shadow: PaymentSheet.ShadowConfig;
        };
        primaryButton: PaymentSheet.PrimaryButtonConfig;
        embeddedPaymentElement: PaymentSheet.EmbeddedPaymentElementAppearance;
        formInsetValues: PaymentSheet.EdgeInsetsConfig;
        applyLiquidGlass?: boolean;
        navigationBarStyle?: PaymentSheet.NavigationBarStyle;
    },
>

Customizes the appearance of EmbeddedPaymentElement

OptionalprimaryButtonLabel

primaryButtonLabel?: string

The label to use for the primary button. If not set, Payment Sheet will display suitable default labels for payment and setup intents.

OptionalremoveSavedPaymentMethodMessage

removeSavedPaymentMethodMessage?: string

Optional configuration to display a custom message when a saved payment method is removed. iOS only.

OptionalpreferredNetworks

preferredNetworks?: CardBrand[]

The list of preferred networks that should be used to process payments made with a co-branded card. This value will only be used if your user hasn't selected a network themselves.

OptionalpaymentMethodOrder

paymentMethodOrder?: String[]

By default, EmbeddedPaymentElement will use a dynamic ordering that optimizes payment method display for the customer. You can override the default order in which payment methods are displayed in EmbeddedPaymentElement with a list of payment method types. See https://stripe.com/docs/api/payment_methods/object#payment_method_object-type for the list of valid types. You may also pass external payment methods.

  • Example: ["card", "external_paypal", "klarna"]
  • Note: If you omit payment methods from this list, they’ll be automatically ordered by Stripe after the ones you provide. Invalid payment methods are ignored.

OptionalallowsRemovalOfLastSavedPaymentMethod

allowsRemovalOfLastSavedPaymentMethod?: boolean

This is an experimental feature that may be removed at any time. Defaults to true. If true, the customer can delete all saved payment methods. If false, the customer can't delete if they only have one saved payment method remaining.

OptionalcardBrandAcceptance

cardBrandAcceptance?: PaymentSheet.CardBrandAcceptance

By default, EmbeddedPaymentElement will accept all supported cards by Stripe. You can specify card brands EmbeddedPaymentElement should block or allow payment for by providing an array of those card brands. Note: This is only a client-side solution. Note: Card brand filtering is not currently supported in Link.

OptionalformSheetAction

formSheetAction?: EmbeddedFormSheetAction

The view can display payment methods like “Card” that, when tapped, open a sheet where customers enter their payment method details. The sheet has a button at the bottom. formSheetAction controls the action the button performs. Defaults to 'continue'.

OptionalcustomPaymentMethodConfiguration

customPaymentMethodConfiguration?: PaymentSheet.CustomPaymentMethodConfiguration

Configuration for custom payment methods in EmbeddedPaymentElement.

OptionalrowSelectionBehavior

rowSelectionBehavior?: EmbeddedRowSelectionBehavior

Describes how the EmbeddedPaymentElement handles payment method row selections.

OptionalembeddedViewDisplaysMandateText

embeddedViewDisplaysMandateText?: boolean

Controls whether the view displays mandate text at the bottom for payment methods that require it. If set to false, your integration must display PaymentOptionDisplayData.mandateHTML to the customer near your "Buy" button to comply with regulations. Note: This doesn't affect mandates displayed in the form sheet. Defaults to true.

Settings

Member Visibility

On This Page

Properties