Get started with Connect embedded components
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:
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_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. | 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 language passed in isn’t directly supported, a reasonable alternative is used (for example fr-be might fall back to fr-fr ). | 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
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.initialize
takes an array of CssFontSource or CustomFontSource objects.
If you’re using custom fonts in your page (that is, .woff
or .tff
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.googleapis.com/css?family=Open+Sans |
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.com/assets/avenir.woff) |
A valid 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. | ||
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
. Note: this is the default value of the header, so not setting this header works.
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 aren’t supported in webviews, they are only supported in standalone browsers.
Supported languages
We localized Connect embedded components for the following languages:
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 |
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.onLoad
if you define it. You can safely initialize Connect.js by setting up an onload
function and calling StripeConnect.init
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–they’ll offer the functionality they’re configured for directly. In some cases, Connect embedded components requires the user to sign in with their Stripe account to perform the necessary functionality required by that component (for example, writing information to the account legal entity in the case of the account onboarding component).
Authentication involves a popup to a Stripe owned window. When the user completes authentication in that popup, it closes and the user can continue their workflow.
The account onboarding and account management components require authentication to boot. Other components might require user authentication within the component after the initial render. Authentication in these components and scenarios is required for all Connect account types except Custom accounts where the platform hasn’t configured external account collection within the Stripe dashboard.