Get started with Connect embedded UIs
Beta

Learn how to embed dashboard functionality into your website.

Connect embedded UIs are available in limited beta. You can try Connect embedded UIs in test mode. To request beta access to live mode, please contact us.

Use Connect embedded UIs 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 UIs 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 UI in the web client to access a connected account’s resources as if you were making the API calls for them.

Connect embedded UIs 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

You can create a new endpoint on your server that will return 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.init` Client

The Connect.js script tag must be added to your page with <script async src=“https://b.stripecdn.com/connect-js/v0.1/connect.js”></script>. This loads the code necessary to connect your page to Stripe. Connect.js is set to load asynchronously in this example to avoid blocking any other assets that are loading in your application.

In this code snippet, window.StripeConnect is conditionally set to the empty object. After Connect.js loads and is ready, the onLoad callback on the window.StripeConnect object runs, kicking off initialization. Initialization takes two required configuration options to init—a publishable key and a client secret.

There’s an HTML element inside of your document called stripe-connect-payments, which is a custom element that Connect.js registers and automatically wires your DOM up to Stripe. The <stripe-connect-payments> element renders a full-fledged payments UI. For the full list of supported embedded UIs, see supported Connect embedded UIs list. Wrap these elements in your own HTML (like the div in the template) to make the inner elements fit seamlessly with your page. 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

<h1>Payments</h1>
<stripe-connect-payments></stripe-connect-payments>
<div class="error" hidden>
  Something went wrong!
</div>

<script async src="https://b.stripecdn.com/connect-js/v0.1/connect.js"></script>
<script>
(async () => {
  // Get the account session from the server
  const response = await fetch('/account_session', { method: "POST" });
  if (!response.ok) {
    // Handle errors on the client side here
    const {error} = await response.json();
    document.querySelector('.error').removeAttribute('hidden');
    return;
  }

  const {client_secret: clientSecret} = await response.json();

  window.StripeConnect ||= {};
  StripeConnect.onLoad = () => {
    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: "pk_test_TYooMQauvdEDq54NiTphI7jx",
      clientSecret
    });
  };
})();
</script>

Configuring Connect.js
Client-side

The init 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 UIs.	optional
`uiConfig`	An object to customize the behavior of Connect embedded UIs.	optional
`refreshClientSecret`	An async function that returns a promise that resolves to a new client secret. This is necessary for Connect embedded UIs to continue working through long running sessions.	optional

Customize the look of Connect embedded UIs

You can customize the font family and your brand color. These customizations affect buttons, icons, and other accents in our design system.

You can set your preferred brand and text link colors when initializing StripeConnect by passing values to the appearance object. These colors apply to all Connect embedded UIs in your application.

StripeConnect.init({
  publishableKey: "pk_test_TYooMQauvdEDq54NiTphI7jx",
  clientSecret: "{{CLIENT_SECRET}}",
  appearance: {
    colors: {
      primary: "#FF0000",
    }
  },
  uiConfig: {
    overlay: "dialog",
  },
  // See all possible variables below
});

The appearance object in StripeConnect.init takes the following optional properties:

Name	Type	Example value
`colors.primary`	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, RGB/RGBA/HSL strings, or global CSS variables (for example, `var(--color)` when `--color: <css color value>` is set using the `:root` selector).

Font family

Additionally, Connect embedded UIs automatically inherit the font family from their immediate parent.

<style>
  .one {
    font-family: 'Georgia', serif;
  }

  .two {
    font-family: 'Gill Sans', sans-serif;
  }

  .three {
    font-family: 'Roboto', sans-serif;
  }
</style>

<body class="one">
  <stripe-connect-payments>></stripe-connect-payments>
  <div class="two">
    <stripe-connect-payments></stripe-connect-payments>
  </div>
  <div class="three">
    <stripe-connect-payments></stripe-connect-payments>
  </div>
</body>

In this example above, the first <stripe-connect-payments> inherits its font family and style from the body element, which is 'Georgia', serif. The second and third elements inherit their font family from their most immediate parent element, respectively set as 'Gill Sans', sans-serif for the element in div two, and 'Roboto', sans-serif for the third element. All other aspects of the font styling, such as size and line-height, are set and managed by the Connect UI design system.

The options listed in this section are the only supported mechanisms for changing the look of Connect embedded UIs. Overriding Connect UI styles with CSS selectors or other mechanisms isn’t supported.

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 init, 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;
}

StripeConnect.init({
  publishableKey: "{{PUBLISHABLE_KEY}}",
  clientSecret: "{{CLIENT_SECRET}}",
  refreshClientSecret: async () => {
    return await fetchClientSecret();
  }
});

Supported Connect embedded UIs

The following Connect embedded UIs 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://b.stripecdn.com; https://js.stripe.com
frame-src, https://b.stripecdn.com
style-src, unsafe-inline

HTTP headers

Setting certain HTTP response headers enables the full functionality of Connect embedded UIs:

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

Get access to live mode
Beta

Interested in using Connect embedded UIs in live mode?

Enter your email below and if you’re eligible for embedded UIs in live mode, we’ll reach out to you with next steps.

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