Get started with Connect embedded components

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

Your app must initiate a request to your server to obtain the account session. You can create a new endpoint on your server that returns the client secret to the app:

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: {
            # Authentication must be disabled for the mobile SDK
            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.

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.

@_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)
    }
}

See a complete list of supported embedded components →

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.

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

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
)

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 .

Configure appearance

Appearance colors using 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.

Update Connect embedded components after initialization

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

var appearance = EmbeddedComponentManager.Appearance()
appearance.colors.primary = UIColor.red

manager.update(appearance: appearance)