# Get started with Connect embedded components Learn how to embed dashboard functionality into your website. Use Connect embedded components to add connected account dashboard functionality to your website. These libraries and their supporting API allow you to grant your users access to Stripe products directly in your dashboard and mobile applications. - **Add integrated UI**: Use embedded components to add integrated UI to your Dashboard. See [all available components](https://docs.stripe.com/connect/supported-embedded-components.md). - **Customize appearance**: Adjust the [appearance](https://docs.stripe.com/connect/customize-connect-embedded-components.md) to match your brand. - **Stay current**: Connect embedded components stay in sync with Stripe APIs, which helps keep your integration up to date. For an immersive version of this guide, see the [Connect embedded components integration quickstart](https://docs.stripe.com/connect/connect-embedded-components/quickstart.md). You can also download a sample integration from there. To customize the appearance of Connect embedded components, use the `appearance` options when you initialize `StripeConnectInstance`. See the [full list of appearance parameters](https://docs.stripe.com/connect/customize-connect-embedded-components.md). ## Initialize Connect.js [Client-side] [Server-side] Stripe uses an [AccountSession](https://docs.stripe.com/api/account_sessions.md) to express your intent to delegate API access to your connected account. The AccountSessions API returns a *client secret* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) that allows an embedded component to access a connected account’s resources as if you were making the API calls for them. ### Create an AccountSession (Server) In a single page application, your client initiates a request to obtain the account session to your server. You can create a new endpoint on your server that returns the client secret to the browser: #### Ruby ```ruby require 'sinatra' require 'stripe' # This is a placeholder - it should be replaced with your API key. # Sign in to see your own test API key embedded in code samples. # Don't put any keys in code. We recommend using a restricted API key with access only to the account sessions resource. See https://docs.stripe.com/keys-best-practices client = Stripe::StripeClient.new('<>') post '/account_session' do content_type 'application/json' # Create an AccountSession begin account_session = client.v1.account_sessions.create({ account: {{CONNECTED_ACCOUNT_ID}}, components: { payments: { enabled: true, features: { refund_management: true, dispute_management: true, capture_payments: true } } } }) { client_secret: account_session[:client_secret] }.to_json rescue => error puts "An error occurred when calling the Stripe API to create an account session: #{error.message}"; return [500, { error: error.message }.to_json] end end ``` ### Create Account Session API The [Create Account Session API](https://docs.stripe.com/api/account_sessions/create.md) determines component and feature access for Connect embedded components. Stripe enforces these parameters for any components that correspond to the account session. If your site supports multiple user roles, make sure components and features that are enabled for that account session correspond to the current user’s role. For example, you can enable [refund management](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-payments-features-refund_management) only for administrators of your site, but not for other users. To make sure user role access are enforced, you must map your site’s user role to account session components. ### Set up Connect.js (Client) We recommend setting up Connect.js with npm as shown in the following example, but it’s also possible [without npm](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#without-npm). #### HTML + JS Install the [npm package](https://github.com/stripe/connect-js) to use Connect.js as a module. ```bash npm install --save @stripe/connect-js ``` #### React Install Connect.js and the React Connect.js libraries from the [npm public registry](https://www.npmjs.com/package/@stripe/react-connect-js). ```bash npm install --save @stripe/connect-js @stripe/react-connect-js ``` ### Load and initialize Connect.js (Client) Call `loadConnectAndInitialize` with your publishable key and a function that retrieves a client secret by calling the new endpoint you created on your server. Use the returned `StripeConnectInstance` to create embedded components. After initializing Connect.js, you can mount components to or unmount components from the DOM at any time. That includes any elements rendered inside React or Vue portals. #### HTML + JS To create a component, call `create` on the `StripeConnectInstance` that you created above, then pass in the component name. This returns a [custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) that Connect.js registers and uses to automatically wire your DOM up to Stripe. You can then `append` this element to your DOM. Call `create` with `payments`, then add the result to your DOM to render a payments UI. #### React To use Connect embedded components with React wrappers, wrap your application in a `ConnectComponentsProvider` and pass in the `StripeConnectInstance` that you previously created. Use `ConnectPayments` on your page to render a payments UI. #### React ```html
``` ```jsx import { createRoot } from 'react-dom/client'; import App from './App'; const root = createRoot(document.getElementById('root')); root.render(); ``` ```jsx import {loadConnectAndInitialize} from '@stripe/connect-js'; import { ConnectPayments, ConnectComponentsProvider, } from "@stripe/react-connect-js"; export default function App() { const [errorMessage, setErrorMessage] = useState(''); // We use `useState` to ensure the Connect instance is only initialized once const [stripeConnectInstance] = useState(() => { const fetchClientSecret = async () => { // Fetch the AccountSession client secret const response = await fetch('/account_session', { method: "POST" }); if (!response.ok) { // Handle errors on the client side here const {error} = await response.json(); console.error('An error occurred: ', error); setErrorMessage(error) return undefined; } else { const {client_secret: clientSecret} = await response.json(); return clientSecret; } } return loadConnectAndInitialize({ // This is a placeholder - it should be replaced with your publishable API key. // Sign in to see your own test API key embedded in code samples. // Don't submit any personally identifiable information in requests made with this key. publishableKey: "<>", fetchClientSecret: fetchClientSecret, }) }); return ( <> {errorMessage ? (
{`Error: ${errorMessage}`}
) : (
)} ); } ``` [See a complete list of supported embedded components →](https://docs.stripe.com/connect/supported-embedded-components.md) ## Configure Connect.js [Client-side] The `loadConnectAndInitialize` method on the client takes several different options to configure Connect.js. | Option | Description | | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `publishableKey` | The [publishable key](https://docs.stripe.com/keys.md) for your integration. | required | | `fetchClientSecret` | The function that retrieves the *client secret* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) returned by `/v1/account_sessions`. This tells `StripeConnectInstance` which account to delegate access to. This function is also used to retrieve a client secret function to refresh the session when it expires. `fetchClientSecret` should always create a new account session and return a fresh `client_secret`. | required | | `appearance` | An object to customize the look of Connect embedded components. | optional | | `locale` | A parameter to specify the [locale](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#localization) that Connect embedded components use. The locale defaults to the browser language. If the specified locale isn’t directly supported, we use a reasonable alternative (for example `fr-be` might fall back to `fr-fr`). See [localization](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#localization) for the list of supported locales. | optional | | `fonts` | An array of custom fonts available for use by any embedded components created from a `StripeConnectInstance`. You can specify fonts as [CssFontSource](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#css-font-source) or [CustomFontSource](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#custom-font-source) objects. | optional | | `displayOptions` | Options to change how embedded components display information. You can specify whether embedded components render object IDs using the [showObjectIds](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#display-options) parameter. | optional | ### Customize the look of Connect embedded components The [embedded components Figma UI toolkit](https://www.figma.com/community/file/1438614134095442934) contains every component, common patterns, and an example application. You can use it to visualize and design embedded UIs on your website. We offer a [set of options](https://docs.stripe.com/connect/embedded-appearance-options.md) to customize the look and feel of Connect embedded components. These customizations affect buttons, icons, and other accents in our design system. > #### Necessary popups > > Some behavior in embedded components, such as [user authentication](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components), must be presented in a popup. You can’t customize the embedded component to eliminate such popups. You can set these options when initializing `StripeConnectInstance` by passing an Appearance to the `appearance` object. You can only use the [Connect.js options](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#configuring-connect) to modify styles in Connect embedded components. The font family and background color of Connect embedded components are inherited from the parent HTML container. You must explicitly set all other options. ```javascript const stripeConnectInstance = loadConnectAndInitialize({ publishableKey: "<>", fetchClientSecret: fetchClientSecret, fonts: [ { cssSrc: "https://myfonts.example.com/mycssfile.css", }, { src: `url(https://my-domain.com/assets/my-font-2.woff)`, family: 'My Font' } ], appearance: { // See all possible variables below overlays: "dialog", variables: { fontFamily: 'My Font', colorPrimary: "#FF0000", }, }, }); ``` See the [full list of appearance variables](https://docs.stripe.com/connect/embedded-appearance-options.md). ### The fonts object The `fonts` object in `stripeConnect.initialize` takes an array of [CssFontSource](https://docs.stripe.com/js/appendix/css_font_source_object) or [CustomFontSource](https://docs.stripe.com/js/appendix/custom_font_source_object) objects. If you use custom fonts on your page (for example, `.woff` or `.tff` files), you must specify the font files when initializing Connect embedded components. Doing so allows Connect embedded components to properly render the fonts. You can specify the files as: #### CssFontSource Use this object to pass a stylesheet URL that defines your custom fonts when creating a `StripeConnectInstance`. With a `CssFontSource` object, your [CSP configuration](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#csp-and-http-header-requirements) must allow fetching the domains associated with the CSS file URLs specified as CssFontSource. | Name | Type | Example value | | -------- | ----------------- | --------------------------------------------------- | | `cssSrc` | string `required` | `https://fonts.googleapis.com/css?family=Open+Sans` | A relative or absolute URL pointing to a CSS file with [@font-face](https://developer.mozilla.org/en/docs/Web/CSS/@font-face) definitions. The file must be hosted on https. If you use a [content security policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy), the file might require [additional directives](https://docs.stripe.com/security/guide.md#content-security-policy). | #### CustomFontSource Use this object to pass custom fonts when creating a `StripeConnectInstance`. | Name | Type | Example value | | -------------- | ----------------- | ----------------------------------------------- | | `family` | string `required` | `Avenir` | The name to give the font. | | `src` | string `required` | `url(https://my-domain.com/assets/avenir.woff)` | A valid [src](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src) value pointing to your custom font file. This is usually (though not always) a link to a file with a `.woff`, `.otf`, or `.svg` suffix. The file must be hosted on https. | | `display` | string `optional` | `auto` | A valid [font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) value. | | `style` | string `optional` | `normal` | One of `normal`, `italic`, or `oblique`. | | `unicodeRange` | string `optional` | `U+0-7F` | A valid [unicode-range](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range) value. | | `weight` | string `optional` | `400` | A valid [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight). This is a string, not a number. | ### Update Connect embedded components after initialization The `update` method supports updating Connect embedded components after initialization. You can use it to switch appearance options at runtime (without refreshing the page). To do so, use the same `stripeConnectInstance` object you created with `initialize` and call the `update` method on it: ```javascript stripeConnectInstance.update({ appearance: { variables: { colorPrimary: "#FF0000", }, }, locale: 'en-US', displayOptions: { showObjectIds: true, } }); ``` > The update method supports a subset of the options supported by `initialize`. You can only update `appearance`, `locale`, and `displayOptions`. ### Width and height Connect embedded components behave like regular `block` HTML elements. By default, they take 100% of the `width` of their parent HTML element, and grow in height according to the content rendered inside. You can control the `width` of Connect embedded components by specifying the `width` of the HTML parent. You can’t directly control the `height` as that depends on the rendered content, however, you can limit the height with `maxHeight` and `overflow: scroll`, the same way you can with other HTML `block` elements. ### Display options By default, Connect embedded components don’t display the IDs of API objects (such as `PaymentIntents`, `Charges`, and `Disputes`). To enable showing object IDs throughout your embedded components, set `displayOptions: { showObjectIds: true }` on your `stripeConnectInstance`. ## Authentication We offer a set of APIs to manage account sessions and user credentials in Connect embedded components. ### Refresh the client secret On long running sessions, the session from the initially provided *client secret* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) might expire. When it expires, we automatically use `fetchClientSecret` to retrieve a new client secret and refresh the session. You don’t need to pass in any additional parameters. ```javascript import { loadConnectAndInitialize } from "@stripe/connect-js"; // Example method to retrieve the client secret from your server const fetchClientSecret = async () => { const response = await fetch('/account_session', { method: "POST" }); const {client_secret: clientSecret} = await response.json(); return clientSecret; } const stripeConnectInstance = loadConnectAndInitialize({ publishableKey: "{{PUBLISHABLE_KEY}}", fetchClientSecret: fetchClientSecret, }); ``` ### Log out We recommend that you call `logout` on the `stripeConnectInstance` to destroy the associated account session object after a user logs out of your app. This disables all Connect embedded components that link to that `stripeConnectInstance`. > #### Necessary popups > > Only call `logout` when your user logs out of your app. Don’t call logout when a component unmounts (when navigating to another page or closing the page) or when loading other components as this method entirely invalidates the current account session and [stripe user session](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=web#user-authentication-in-connect-embedded-components). After calling `logout`, components no longer render for the associated `stripeConnectInstance`. ```javascript // Call this when your user logs out stripeConnectInstance.logout(); ``` ## CSP and HTTP header requirements If your website implements a *Content Security Policy* (Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross-Site Scripting (XSS) and data injection attacks), you need to update the policy by adding the following rules: - `frame-src`, `https://connect-js.stripe.com`, `https://js.stripe.com` - `img-src`, `https://*.stripe.com` - `script-src`, `https://connect-js.stripe.com`, `https://js.stripe.com` - `style-src`, `sha256-0hAheEzaMe6uXIKV4EehS9pu1am1lj/KnnzrOYqckXk=` (SHA of empty style element) If you’re using a CSS file to load [web fonts](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#fonts-object) for use with Connect embedded components, its URL must be allowed by your [connect-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/connect-src) CSP directive. Setting certain [HTTP response headers](https://developer.mozilla.org/en-US/docs/Glossary/Response_header) enables the full functionality of Connect embedded components: - [Cross-Origin-Opener-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy), `unsafe-none`. This (`unsafe-none`) is the default value of the header, so not setting this header works. Other values such as `same-origin` break [user authentication](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components) in Connect embedded components. ## Supported browsers We support the same set of browsers that the [Stripe Dashboard currently supports](https://docs.stripe.com/dashboard/basics.md): - The last 20 major versions of Chrome and Firefox - The last two major versions of Safari and Edge - The last two major versions of mobile Safari on iOS You can’t use Connect embedded components in embedded web views inside mobile or desktop applications. To use Connect embedded components in a mobile application, use the [iOS](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=ios), [Android](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=android), or [React Native](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=react-native) SDK. If an embedded component isn’t supported yet by our mobile SDKs, we recommend linking to a web browser where you can render the embedded components. ## Localization When initializing [Connect.js](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), you can pass a `locale` parameter. To match an embedded component’s locale to your website’s locale, pass the `locale` parameter with the locale of the UI your website renders. The default value of the `locale` parameter is determined by the browser configured locale. If the specified locale isn’t directly supported, a reasonable alternative is used (for example `fr-be` might fall back to `fr-fr`). Connect embedded components support the following locales: | Language | Locale code | | --------------------------------- | ------------ | | Bulgarian (Bulgaria) | `bg-BG` | | Chinese (Simplified) | `zh-Hans` | | Chinese (Traditional - Hong Kong) | `zh-Hant-HK` | | Chinese (Traditional - Taiwan) | `zh-Hant-TW` | | Croatian (Croatia) | `hr-HR` | | Czech (Czechia) | `cs-CZ` | | Danish (Denmark) | `da-DK` | | Dutch (Netherlands) | `nl-NL` | | English (Australia) | `en-AU` | | English (India) | `en-IN` | | English (Ireland) | `en-IE` | | English (New Zealand) | `en-NZ` | | English (Singapore) | `en-SG` | | English (United Kingdom) | `en-GB` | | English (United States) | `en-US` | | Estonian (Estonia) | `et-EE` | | Filipino (Philippines) | `fil-PH` | | Finnish (Finland) | `fi-FI` | | French (Canada) | `fr-CA` | | French (France) | `fr-FR` | | German (Germany) | `de-DE` | | Greek (Greece) | `el-GR` | | Hungarian (Hungary) | `hu-HU` | | Indonesian (Indonesia) | `id-ID` | | Italian (Italy) | `it-IT` | | Japanese (Japan) | `ja-JP` | | Korean (South Korea) | `ko-KR` | | Latvian (Latvia) | `lv-LV` | | Lithuanian (Lithuania) | `lt-LT` | | Malay (Malaysia) | `ms-MY` | | Maltese (Malta) | `mt-MT` | | Norwegian Bokmål (Norway) | `nb-NO` | | Polish (Poland) | `pl-PL` | | Portuguese (Brazil) | `pt-BR` | | Portuguese (Portugal) | `pt-PT` | | Romanian (Romania) | `ro-RO` | | Slovak (Slovakia) | `sk-SK` | | Slovenian (Slovenia) | `sl-SI` | | Spanish (Argentina) | `es-AR` | | Spanish (Brazil) | `es-BR` | | Spanish (Latin America) | `es-419` | | Spanish (Mexico) | `es-MX` | | Spanish (Spain) | `es-ES` | | Swedish (Sweden) | `sv-SE` | | Thai (Thailand) | `th-TH` | | Turkish (Türkiye) | `tr-TR` | | Vietnamese (Vietnam) | `vi-VN` | ## Handle load errors If a component fails to load, you can react to the failure by providing a load error handler to any embedded component. Depending on the cause of failure, the load error handler can be called multiple times. Any logic triggered by a load error handler must be idempotent. #### React ```jsx // Load errors are emitted by all components. We use Balances as an example here. import { ConnectBalances, ConnectComponentsProvider, } from '@stripe/react-connect-js'; const BalancesUI = () => { const onLoadError = (loadError) => { const componentName = loadError.elementTagName const error = loadError.error console.log(componentName + " failed to load") console.log(`${error.type}: ${error.message}`); }; return ( ); }; ``` #### HTML + JS | Method | Description | Variables | | ---------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `setOnLoadError` | The component executes this callback function when a load failure occurs. | - `loadError.error`: See [the load error object](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#the-load-object) - `loadError.elementTagName`: The name of HTML tag used to render the component in the browser | #### React | React prop | Description | Variables | | ------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onLoadError` | The component executes this callback function when a load failure occurs. | - `loadError.error`: See [the load error object](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#the-load-object) - `loadError.elementTagName`: The name of HTML tag used to render the component in the browser | #### The load `error` object Every time there’s a load failure, an `error` object is passed to the load error handler with the following properties. | Name | Type | Example value | | --------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | | `type` | See [types of load failures](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#the-load-object) | `authentication_error` | The type of error | | `message` | string | undefined | `Failed to fetch account session` | Further description about the error | #### Types of load failures When a component fails to load, we detect the type of failure and map it to one of the types below. If the load error type can’t be determined it’s marked as an `api_error`. | Type | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------ | | `api_connection_error` | Failure to connect to Stripe’s API | | `authentication_error` | Failure to perform the authentication flow within Connect embedded components | | `account_session_create_error` | Account session creation failed | | `invalid_request_error` | Request failed with an 4xx status code, typically caused by platform configuration issues | | `rate_limit_error` | Request failed because an abnormal request rate was detected | | `render_error` | Failure to render the component, typically caused by browser extensions or network issues | | `api_error` | API errors covering any other type of problem, such as a temporary problem with Stripe’s servers | #### UI for load errors In most cases, embedded components render an error message when they fail to load, so you don’t need to. You can use a load error handler for analytics or for other elements of your site that a load error might affect. However, embedded components don’t render any message for errors that occur prior to invoking the [onLoaderStart](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=web#reacting-to-component-display) callback, because that means they haven’t rendered any UI at all. In that case, your code should render the error UI. ## Detect the display of embedded components After a component is created, no UI is displayed to users until the javascript for the component is loaded and parsed in the browser. This can cause components to appear to pop-in after they complete loading. To avoid this, display your own loading UI before the component is created and hide the UI after the component is displayed. All embedded components can accept a callback function that is called immediately when any UI (including loading indicators) is displayed to the user. #### React ```jsx // Loader start events are emitted by all components. We use Balances as an example here. import { ConnectBalances, ConnectComponentsProvider, } from '@stripe/react-connect-js'; const BalancesUI = () => { const [loading, setLoading] = useState(true); const onLoaderStart = (event) => { setLoading(false); console.log(`${event.elementTagName} is visible to users`) }; return ( {loading && } ); }; ``` #### HTML + JS | Method | Description | Variables | | ------------------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | `setOnLoaderStart` | The component executes this callback function when any UI (including loading indicators) is displayed to the user. | - `event.elementTagName`: The name of HTML tag used to render the component in the browser | #### React | React prop | Description | Variables | | --------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | `onLoaderStart` | The component executes this callback function when any UI (including loading indicators) is displayed to the user. | - `event.elementTagName`: The name of HTML tag used to render the component in the browser | ## Use Connect.js without npm We recommend integrating with our [javascript](https://github.com/stripe/connect-js) and [React component wrappers](https://github.com/stripe/react-connect-js), which simplify the loading of Connect embedded components and provide TypeScript definitions for our supported interfaces. If your build system currently doesn’t support taking a dependency on packages, you can integrate without these packages. Manually add the Connect.js script tag to the `` of each page on your site. ```html ``` After Connect.js completes loading, it initializes the global window variable `StripeConnect` and calls `StripeConnect.onLoad`, if defined. You can safely initialize Connect.js by setting up an `onload` function and calling `StripeConnect.init` with the same [Connect.js options](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#configuring-connect) as `loadConnectAndInitialize`. You can use the Connect instance returned by `init` in the same way you use the instance returned by `loadConnectAndInitialize` to create embedded components in an [HTML + JS integration](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?client=js&platform=web#load-and-initialize-connectjs). ```javascript window.StripeConnect = window.StripeConnect || {}; StripeConnect.onLoad = () => { const stripeConnectInstance = StripeConnect.init({ // This is a placeholder - it should be replaced with your publishable API key. // Sign in to see your own test API key embedded in code samples. // Don't submit any personally identifiable information in requests made with this key. publishableKey: "<>", fetchClientSecret: fetchClientSecret, }); const payments = stripeConnectInstance.create('payments'); document.body.appendChild(payments); }; ``` ## User authentication in Connect embedded components Connect embedded components typically don’t require user authentication. In some scenarios, Connect embedded components require the connected account to sign in with their Stripe account before accessing the component to provide the necessary functionality (for example, writing information to the account legal entity in the case of the [account onboarding](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md) component). Other components might require authentication within the component after they initially render. Authentication is required for connected accounts where Stripe is responsible for collecting updated information when requirements change. For connected accounts where you’re responsible for collecting updated information when requirements are due or change, such as Custom accounts, Stripe authentication is controlled by the [disable_stripe_user_authentication](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_onboarding-features-disable_stripe_user_authentication) Account Session feature. We recommend implementing 2FA or equivalent security measures as a [best practice](https://docs.stripe.com/connect/risk-management/best-practices.md#prevent-account-take-overs). For account configurations that support this feature, like Custom, you assume liability for connected accounts if they can’t pay back [negative balances](https://docs.stripe.com/connect/risk-management/best-practices.md#decide-your-approach-to-negative-balance-liability). ### Components requiring authentication Authentication includes a popup to a Stripe-owned window. The connected account must authenticate before they can continue their workflow. The following components require connected accounts to authenticate in certain scenarios: - [Account Onboarding](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md) - [Account Management](https://docs.stripe.com/connect/supported-embedded-components/account-management.md) - [Balances](https://docs.stripe.com/connect/supported-embedded-components/balances.md) - [Payouts](https://docs.stripe.com/connect/supported-embedded-components/payouts.md) - [Notification Banner](https://docs.stripe.com/connect/supported-embedded-components/notification-banner.md) - [Financial Account](https://docs.stripe.com/connect/supported-embedded-components/financial-account.md) - [Issuing Cards List](https://docs.stripe.com/connect/supported-embedded-components/issuing-cards-list.md) ## Performance best practices To make sure the load time of Connect embedded components is as low as possible, follow these recommendations: - **Call `loadConnectAndInitialize` as early as possible in your flow**. - **Create a single connect instance**: Create a single Connect instance by calling `loadConnectAndInitialize` only once per session. Then reuse that instance to create and manage multiple components. A common mistake is to create one Connect instance per component or multiple Connect instances per session. This can increase resource use and API requests. If you use React, use a state management library or React context to manage this instance. Refer to the [code samples](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=web#load-and-initialize-connectjs) on this page. - **Use the latest version of the appropriate SDKs**: Use the latest version of the [connect-js](https://www.npmjs.com/package/@stripe/connect-js) or [react-connect-js](https://www.npmjs.com/package/@stripe/react-connect-js) npm package SDKs. These SDKs initialize embedded components in a way that maximizes performance. Performance improvements have been added to the SDKs, so we recommend upgrading if you’re using an old version. - **Load the `connect.js` script as soon as possible in your flow**: The earliest possible place to load the script is by including this script in your HTML `head`. You can also use the default behavior of our npm package SDKs, which load it when your page JavaScript first loads. - **Avoid mounting and unmounting component unnecessarily**: Avoid rendering loops that repeatedly mount and unmount a component. Each time a component mounts, its loading cycle starts again, which can reduce performance and increase browser resource use. Only mount and unmount a component when necessary. - **Look for console warnings when testing your component**: Embedded components log warnings to the browser console for common integration issues. Before releasing your app, test it and check the console for warnings.