Get started with Connect embedded components
Beta

Learn how to embed dashboard functionality into your website.

Beta

Connect embedded components are available in limited beta. To request beta access, please contact us.

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.

Initialize Connect.js
Client-side
Server-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.

Note

Connect embedded components are in beta. To create an account session, you can use the Stripe beta SDKs:

Ruby >=7.2.0-beta.1
Python >=4.2.0b1
PHP >=9.3.0-beta.1
Node >=10.4.0-beta.1
.NET >=40.4.0-beta.1
Java >=21.3.0-beta.2
Go >=73.4.0-beta.1

For a working code sample on these languages, you can also see our quickstart guide.

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:

main.rb

require 'sinatra'
require 'stripe'
# This is a placeholder - it should be replaced with your secret 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.
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe.api_version = '2022-11-15; embedded_connect_beta=v1'

post '/account_session' do
  content_type 'application/json'

  # Create an AccountSession
  begin
    account_session = Stripe::AccountSession.create({
      account: '{{CONNECTED_ACCOUNT_ID}}'
    })

    {
      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

Include `Connect.js` and call `StripeConnect.initialize` Client

We provide an npm package that allows you to load and use Connect.js as a module.

In this code snippet, loadConnect() asynchronously appends the Connect.js script to the page HTML. loadConnect() returns a stripeConnect object. stripeConnect.initialize takes two required configuration options—a publishable key and a client secret, and returns a StripeConnectInstance which you can use to create embedded components.

Your document has an HTML element inside it called stripe-connect-payments, which is a custom element that Connect.js registers and uses it to automatically wire your DOM up to Stripe. The <stripe-connect-payments> element renders a full payments UI. For the entire list of supported embedded components, see supported Connect embedded components list. Wrap these elements in your own HTML (in the same manner as the div in the template) to make the inner elements fit with your page. We also provide React component wrappers for these elements. After initialization, mount or unmount these elements from the DOM at any time. This includes any elements rendered inside React or Vue portals.

On the client side, retrieve the client secret by calling the new endpoint you created on your server using the browser’s fetch function:

index.html

<head>
  <script type="module" src="index.js" defer></script>
  <body>
    <h1>Payments</h1>
    <stripe-connect-payments></stripe-connect-payments>
    <div class="error" hidden>Something went wrong!</div>
  </body>
</head>

index.js

import {loadConnect} from '@stripe/connect-js`;

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);
    document.querySelector('.error').removeAttribute('hidden');
    return undefined;
  } else {
    const {client_secret: clientSecret} = await response.json();
    document.querySelector('.error').setAttribute('hidden', '');
    return clientSecret;
  }
}
const clientSecret = await fetchClientSecret();
const stripeConnect = await loadConnect();
if (clientSecret) {
  const connectInstance = stripeConnect.initialize({
    // 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: "pk_test_TYooMQauvdEDq54NiTphI7jx",
    clientSecret,
    // Returns a new client secret on long running sessions
    // when the initially provided client secret might expire.
    refreshClientSecret: fetchClientSecret
  });
};

Configuring Connect.js
Client-side

The initialize method of stripeConnect on the client takes several different options to configure Connect.js.

Option	Description
`publishableKey`	The publishable key for your integration.	required
`clientSecret`	The client secret returned by `/v1/account_sessions`. This tells `StripeConnect` which account to delegate access to.	required
`appearance`	An object to customize the look of Connect embedded components.	optional
`uiConfig`	An object to customize the behavior of Connect embedded components.	optional
`refreshClientSecret`	An async function that returns a promise that resolves to a new client secret. This is necessary for Connect embedded components to continue working through long running sessions.	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

Customize the look of Connect embedded components

We offer a set of options to customize the look 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. These colors apply to all Connect embedded components in your application. The Connect.js options are the only supported mechanisms for changing styles in Connect embedded components. Overriding Connect embedded component styles with CSS selectors or other mechanisms isn’t supported.

const stripeConnectInstance = stripeConnect.initialize({
  publishableKey: "pk_test_TYooMQauvdEDq54NiTphI7jx",
  clientSecret: "{{CLIENT_SECRET}}",
  appearance: {
    colorPrimary: "#FF0000",
  },
  uiConfig: {
    overlay: "dialog",
  },
  // See all possible variables below
});

The appearance object in stripeConnect.initialize takes the following optional properties:

Name	Type	Example value
`colorPrimary`	string	#FF0000
A primary color used throughout the Connect.js design system. Set this string to your CSS primary brand color. You can use hex values or RGB/RGBA/HSL strings.
`fontFamily`	string	sans-serif
A font family value specified in the `appearance` object takes precedence over the `font-family` value inherited from the immediate parent element of each embedded component.

Refreshing the client secret

On long running sessions, the session from the initially provided client secret might expire. When it expires, subsequent calls to the API fail if the session isn’t refreshed. To refresh the session, add refreshClientSecret to initialize, which accepts an async function that calls your server and returns a new client secret.

// 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 = stripeConnect.initialize({
  publishableKey: "{{PUBLISHABLE_KEY}}",
  clientSecret: "{{CLIENT_SECRET}}",
  refreshClientSecret: async () => {
    return await fetchClientSecret();
  }
});

Supported Connect embedded components

Add Connect embedded components to your page as HTML Elements or as React components. The following Connect embedded components are available:

Payments

Payment details

Payouts

CSP requirements

If your website implements a Content Security Policy, you need to update the policy by adding the following rules:

script-src, https://connect-js.stripe.com; https://js.stripe.com
frame-src, https://connect-js.stripe.com
style-src, unsafe-inline

HTTP headers

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.

Error handling

The AccountSession API can return specific 40x errors. See the error code reference for a list of all error codes.

The following table describes how to handle errors that are specific to AccountSession. See the error handling guide for more general guidance.

Error code	Reason
`invalid_request_error`	The beta header is missing and needs to be specified.
`parameter_missing`	The account parameter hasn’t been passed in.
`resource_missing`	No account has that specified ID, or no account exists with that ID that matches the livemode of the API key.

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

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 (Turkey)	`tr-TR`
Vietnamese (Vietnam)	`vi-VN`

Get access to embedded components
Beta

Interested in using Connect embedded components?

Enter your email below and we’ll reach out to you with next steps.

Signed up successfully!
Thank you! We'll be in touch soon.

Apr	MAY	Jun
	10
2022	2023	2024