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.
For an immersive version of this guide, see the Connect embedded components integration quickstart. 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.
Initialize Connect.jsClient-sideServer-side
Stripe uses an AccountSession to express your intent to delegate API access to your connected account.
The AccountSessions API returns a client secret that allows an embedded component in the web client 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:
Create Account Session API
The Create Account Session API 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 only for administrators of your site, but not for other users. To ensure user role access are enforced, your backend must host the logic that maps your site’s user role to account session components.
Set up Connect.js Client
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.
Configuring Connect.jsClient-side
The loadConnectAndInitialize
method on the client takes several different options to configure Connect.js.
Option | Description | |
---|---|---|
publishableKey | The publishable key for your integration. | required |
fetchClientSecret | The function that retrieves the client secret returned by /v1/account_ . 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. | required |
appearance | An object to customize the look of Connect embedded components. | optional |
locale | A parameter to specify the locale that Connect embedded components use. The locale defaults to the browser language. If the specified locale isn’t directly supported, a reasonable alternative is used (for example fr-be might fall back to fr-fr ). See 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 . Fonts can be specified as CssFontSource or CustomFontSource objects. | optional |
Customize the look of Connect embedded components
The embedded components Figma UI toolkit contains every component, common patterns, and an example application. You can use it to visualize and design embedded UIs in your website.
We offer a set of options to customize the look and feel of Connect embedded components. These customizations affect buttons, icons, and other accents in our design system.
You can set these options when initializing StripeConnectInstance
by passing values to the appearance
object. You can only use the Connect.js options to modify styles in Connect embedded components. The font family and background color of Connect embedded components can be overridden with CSS selectors, but Stripe doesn’t support overriding any other styles.
const fetchClientSecret = async () => { const response = await fetch('/account_session'); const {client_secret: clientSecret} = await response.json(); return clientSecret; } 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", }, }, });"pk_test_TYooMQauvdEDq54NiTphI7jx"
The fonts object
The fonts
object in stripeConnect.
takes an array of CssFontSource or CustomFontSource objects.
If you’re using custom fonts in your page (that is, .
or .
files), you must specify these files when initializing Connect embedded components. Doing this allows Connect embedded components to properly render these fonts. You can specify these 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 must allow fetching the domains associated with the CSS file URLs specified as CssFontSource.
Name | Type | Example value |
cssSrc | string required | https://fonts. |
A relative or absolute URL pointing to a CSS file with @font-face definitions. Using a content security policy (CSP) might impose additional directives. |
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. |
A valid src value pointing to your custom font file. This is usually (though not always) a link to a file with a . , . , or . suffix. | ||
display | string optional | auto |
A valid font-display value. | ||
style | string optional | normal |
One of normal , italic , or oblique . | ||
unicodeRange | string optional | U+0-7F |
A valid unicode-range value. | ||
weight | string optional | 400 |
A valid font-weight. Note that this is a string, not a number. |
The appearance object
The appearance
object in loadConnectAndInitialize
takes the following optional properties:
Name | Type | Example value |
overlays | ‘dialog’ (default) | ‘drawer’ | dialog |
The type of overlay used throughout the Connect.js design system. Set this to be either a Dialog or Drawer. | ||
variables | object | {colorPrimary: "#0074D4"} |
See the full list of appearance variables. |
Updating Connect embedded components after initialization
The update
method supports updating Connect embedded components after initialization. This is useful for switching 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:
stripeConnectInstance.update({ appearance: { variables: { colorPrimary: "#FF0000", }, }, locale: 'en-US', });
Note
Not all options (e.g. fonts
) are updatable. The supported options for this method are a subset of the options offered in initialize
. This supports updating the appearance
and locale
.
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
, just like with other HTML block
elements.
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 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.
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'); 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
.
// Call this when your user logs out stripeConnectInstance.logout();
CSP and HTTP header requirements
If your website implements a Content Security Policy, 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 for use with Connect embedded components, its URL must be allowed by your connect-src CSP directive.
Setting certain HTTP response headers enables the full functionality of Connect embedded components:
- Cross-Origin-Opener-Policy,
unsafe-none
. This (unsafe-none
) is the default value of the header, so not setting this header works. Other values likesame-origin
break user authentication in Connect embedded components.
Supported browsers
We support the same set of browsers that the Stripe Dashboard currently supports:
- 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
Connect embedded components are only supported in web browsers and cannot be used in embedded web views inside mobile or desktop applications.
Localization
When initializing Connect.js, 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.
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 | authentication_ | |
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 is marked as an api_
.
Type | Description |
---|---|
api_ | Failure to connect to Stripe’s API |
authentication_ | Failure to perform the authentication flow within Connect embedded components |
account_ | Account session creation failed |
invalid_ | Request failed with an 4xx status code, typically caused by platform configuration issues |
rate_ | Request failed because an abnormal request rate was detected |
api_ | API errors covering any other type of problem, such as a temporary problem with Stripe’s servers |
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 before any UI is displayed to the user.
Integrate without frontend npm packages
We recommend integrating with our javascript and React component wrappers, 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 <head>
of each page on your site.
<!-- Somewhere in your site's <head> --> <script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>
Using Connect.js without NPM
After Connect.js completes loading, it initializes the global window variable StripeConnect
and calls StripeConnect.
if you define it. You can safely initialize Connect.js by setting up an onload
function and calling StripeConnect.
with the same Connect.js options as loadConnectAndInitialize
.
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); };"pk_test_TYooMQauvdEDq54NiTphI7jx"
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 to provide the necessary functionality (for example, writing information to the account legal entity in the case of the account onboarding component).
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
- Account Management
- Balances
- Payouts
- Notification Banner
- Financial Account
- Issuing Cards List
Other components might require authentication within the component after they initially render. Authentication for these components and scenarios 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, Stripe authentication is controlled by the disable_stripe_user_authentication Account Session feature. We recommend implementing 2FA or equivalent security measures as a best practice. For account configurations that support this feature, like Custom, you assume liability for connected accounts if they can’t pay back negative balances.