Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Get started with Connect
Integration fundamentals
Example integrations
Account management
Onboard accounts
Configure account Dashboards
    Get started with Connect embedded components
      Quickstart
    Customize Connect embedded components
    Supported Connect embedded components
    Stripe Dashboard customization
    Platform controls for Stripe Dashboard accounts
    Express Dashboard
Work with connected account types
Payment processing
Accept payments
Pay out to accounts
Platform administration
Manage your Connect platform
Tax forms for your Connect platform
HomePlatforms and marketplacesConfigure account Dashboards

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.

Set up StripeConnect
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 to access a connected account’s resources as if you were making the API calls for them.

Create an AccountSession Server

Your app must initiate a request to your server to obtain the account session. Currently, only Account onboarding is supported. You can create a new endpoint on your server that returns the client secret to the app:

main.rb
Ruby
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_BQokikJOvBiI2HlWgH4olfQ2'
post '/account_session' do content_type 'application/json' # Create an AccountSession begin account_session = Stripe::AccountSession.create({ account:
'{{CONNECTED_ACCOUNT_ID}}'
, components: { account_onboarding: { enabled: true, features: { # We recommend disabling authentication for a better user experience when possible disable_stripe_user_authentication: 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 determines component and feature access for Connect embedded components. Stripe enforces these parameters for any components that correspond to the account session. If your app 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 make sure user role access are enforced, you must map your site’s user role to account session components.

Install the StripeConnect SDK Client

The Stripe iOS SDK is open source, fully documented, and compatible with apps supporting iOS 15 or above.

To install the SDK, follow these steps:

  1. In Xcode, select File > Add Package Dependencies… and enter https://github.com/stripe/stripe-ios-spm as the repository URL.
  2. Select the latest version number from our releases page.
  3. Add the StripeConnect product to the target of your app.

Note

For details on the latest SDK release and past versions, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.

Set up camera authorization Client-side

The Stripe Connect iOS SDK requires access to the device’s camera to capture identity documents. To enable your app to request camera permissions:

  1. Open your project’s Info.plist in Xcode.
  2. Add the NSCameraUsageDescription key.
  3. Add a string value that explains to your users why your app requires camera permissions, something such as:

This app uses the camera to take a picture of your identity documents.

See Apple’s documentation to learn more about requesting camera authorization.

Initialize EmbeddedComponentManager Client

Set your publishable key using StripeAPI.shared and instantiate an EmbeddedComponentManager with a closure that retrieves a client secret by calling the new endpoint you created on your server. To create a component, call the appropriate create method on the EmbeddedComponentManager that you instantiated above. This returns a controller that you can use to present it in the app.

MyViewController.swift
@_spi(PrivateBetaConnect) import StripeConnect import UIKit class MyViewController: UIViewController { let errorView: UIView func fetchClientSecret() async -> String? { let url = URL(string: "https://{{YOUR_SERVER}}/account_session")! var request = URLRequest(url: url) request.httpMethod = "POST" do { // Fetch the AccountSession client secret let (data, _) = try await URLSession.shared.data(for: request) let json = try JSONSerialization.jsonObject(with: data) as? [String : Any] errorView.isHidden = true return json?["client_secret"] as? String } catch let error { // Handle errors on the client side here print("An error occurred: \(error)") errorView.isHidden = false return nil } } override func viewDidLoad() { super.viewDidLoad() // This is your test publishable API key. STPAPIClient.shared.publishableKey = "{{PUBLISHABLE_KEY}}", let embeddedComponentManager = EmbeddedComponentManager( fetchClientSecret: fetchClientSecret ) let controller = embeddedComponentManager.createAccountOnboardingController() controller.present(from: self) } }

Configure the Embedded Component Manager
Client-side

See the code reference .

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 on 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.

Necessary popups

Some behavior in embedded components, such as user authentication, must be presented in an authenticated WebView. You can’t customize the embedded component to eliminate such WebViews.

You can set these options using EmbeddedComponentManager.Appearance when initializing EmbeddedComponentManager.

MyViewController.swift
func fetchClientSecret() async -> String? { let url = URL(string: "https://{{YOUR_SERVER}}/account_session")! var request = URLRequest(url: url) request.httpMethod = "POST" do { let (data, _) = try await URLSession.shared.data(for: request) let json = try JSONSerialization.jsonObject(with: data) as? [String : Any] return json?["client_secret"] as? String } catch { return nil } } // Specify custom fonts var customFonts: [CustomFontSource] = [] let myFont = UIFont(name: "My Font", size: 16)! let fontUrl = Bundle.main.url(forResource: "my-font-2", withExtension: "woff")! do { let customFontSource = try CustomFontSource(font: myFont, fileUrl: fontUrl) customFonts.append(customFontSource) } catch { print("Error loading custom font: \(error)") } // Customize appearance var appearance = EmbeddedComponentManager.Appearance() appearance.typography.fontfont.base = myFont appearance.typography.fontSizeBase = 16 // Unscaled font size appearance.colors.primary = UIColor { traitCollection in if traitCollection.userInterfaceStyle == .dark { UIColor(red: 0.455, green: 0.424, blue: 1.000, alpha: 1.0) } else { UIColor(red: 0.404, green: 0.365, blue: 1.000, alpha: 1.0) } } STPAPIClient.shared.publishableKey = "{{PUBLISHABLE_KEY}}", let embeddedComponentManager = EmbeddedComponentManager( appearance: appearance, fonts: customFonts, fetchClientSecret: fetchClientSecret )

Appearance colors that use dynamic providers are automatically applied to the Connect embedded component when its UITraitCollection is updated, including Dark Mode and accessibility contrast. The default appearance doesn’t include dark mode colors, so you must specify an appearance with dynamic colors to the EmbeddedComponentManager to support dark mode in your app.

When specifying font sizes, use the unscaled font size that displays for the device’s default size class. The embedded component automatically scales the font size based on its UITraitCollection.

See the full list of appearance options on iOS.

Use custom fonts

If you use custom fonts in your app (for example, from .otf or .tff files embedded in your app binary), you must specify the font files in a CustomFontSource passed to the fonts argument when initializing EmbeddedComponentManager. This gives Connect embedded components access to the font files to properly render the fonts.

Fonts specified in appearance must use either a supported system font or a CustomFontSource passed to the EmbeddedComponentManager on initialization to properly render.

See the reference documentation .

Update Connect embedded components after initialization

Call the update method to change the appearance of the embedded components after initialization:

MyViewController.swift
var appearance = EmbeddedComponentManager.Appearance() appearance.colors.primary = UIColor.red manager.update(appearance: appearance)

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.

MyViewController.swift
func fetchClientSecret() async -> String? { var request = URLRequest(url: URL(string: "https://{{YOUR_SERVER}}/account_session")!) request.httpMethod = "POST" do { let (data, _) = try await URLSession.shared.data(for: request) let json = try JSONSerialization.jsonObject(with: data) as? [String : Any] return json?["client_secret"] as? String } catch let error { return nil } } STPAPIClient.shared.publishableKey = "{{PUBLISHABLE_KEY}}", let embeddedComponentManager = EmbeddedComponentManager( fetchClientSecret: fetchClientSecret )

Localization

Connect embedded components support the following locales:

LanguageLocale 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

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 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 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.

Components requiring authentication

Connected accounts will be shown an authenticated WebView within your application. The connected account must authenticate before they can continue their workflow within the WebView.

The Stripe-hosted authentication flow shows your brand’s name, color, and icon as set in your Connect settings and doesn’t use your custom appearance and fonts from the Embedded Component Manager until authentication completes.

The following component requires connected accounts to authenticate in certain scenarios:

  • Account Onboarding

Handle load errors

If a component doesn’t load, you can react to the failure by implementing the component’s didFailLoadWithError delegate method. Depending on the cause of failure, the didFailLoadWithError method might be called multiple times. Any logic triggered by a didFailLoadWithError must be idempotent.

MyViewController.swift
// All components emit load errors. This example uses AccountOnboarding. // All components support didFailLoadWithError. class MyViewController: UIViewController, AccountOnboardingControllerDelegate { func openAccountOnboarding() { let accountOnboardingController = embeddedComponentManager.createAccountOnboardingController(); accountOnboardingController.delegate = self accountOnboardingController.present(from: self) } // MARK: - AccountOnboardingControllerDelegate func accountOnboarding(_ accountOnboarding: AccountOnboardingController, didFailLoadWithError error: Error) { print("Account onboarding failed to load with error '\(error)'") } }
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc