Embedded Stripe Apps integration guideVersion bêta privée

Set up Connect.js to enable the ability to add connected account dashboard functionality to your website.

Embedded Stripe Apps uses private preview components that requires using preview versions of Stripe SDKs. Read more about private preview components.

Stripe supports the following app integrations.

Render the app install embedded component for your selected app. App installation grants permission for the third party app to access your users’ Stripe data, creating a connection between your platform, Stripe, and the third party app. The component has two states: uninstalled and installed. Listen to install event triggers to build your custom UX flow or make updates in your own back end.

When creating an Account Session, enable app installation and rendering by specifying app_install, and app_viewport in the components parameter. You must enable the app you want to render by specifying the features parameter under allowed_apps.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.basil; embedded_connect_beta=v2;" \
  -d account={{CONNECTED_ACCOUNT_ID}} \
  -d "components[app_install][enabled]"=true \
  -d "components[app_install][features][allowed_apps][]"=APP_ID \
  -d "components[app_viewport][enabled]"=true \
  -d "components[app_viewport][features][allowed_apps][]"=APP_ID

After creating the account session and initializing ConnectJS, you can render the App install component in the front end:

const appInstall = stripeConnectInstance.create('app-install');
appInstall.setApp('{{APP_ID}}');
container.appendChild(appInstall);

This embedded component supports the following parameters:

You can configure custom behavior based on the current or updated state of an install.

// index.html
<div id="app-install-container"></div>

// index.js

// Do something when install state fetched on render
const handleAppInstallFetched = (response) => {
  console.log(`Install state fetched for app  ${response.appId} to ${response.state}`);
};

// Do something when install state changes
const handleAppInstallChanged = (response) => {
  console.log(`Install state changed for app  ${response.appId} to ${response.state}`);
};


const container = document.getElementById('app-install-container');
const appInstall = stripeConnectInstance.create('app-install');
appInstall.setApp('{{APP_ID}}');
appInstall.setOnAppInstallStateFetched(handleAppInstallFetched);
appInstall.setOnAppInstallStateChanged(handleAppInstallChanged);
container.appendChild(appInstall);

Render the app viewport embedded component for your selected app to enable core app functionality, including connection to the app’s software account with OAuth, onboarding, settings, and configuration for the service and synchronization states of transactions. Pass the user_id (business represented on your platform) as an optional HTML attribute that third party apps can use to build a dynamic URL that redirects back to your user dashboard after OAuth.

const appViewport = stripeConnectInstance.create('app-viewport');
appViewport.setApp('{{APP_ID}}');
appViewport.setAppData({userId: '{{PLATFORM_USER_ID}}'});
container.appendChild(appViewport);

This embedded component supports the following parameters:

Pass required and optional transaction data to your selected app by updating the destination charge on the connected account using the data standardized data schema below. You must pass a Customer object to the destination charge. You have three scenarios that require you to update your destination charge:

• One-time payment complete
• Recurring payment complete
• Payment refunded

The following code snippet example traverses to the target destination charge and shows how to update per schema.

1. Trace from the Transaction to the destination charge

const paymentOnPlatform = await StripeClient.paymentIntents.retrieve(
  "pi_3N6JL7LirQdaQn8E1Lpn7Dui",
);

const latestCharge = await StripeClient.charges.retrieve(
  paymentOnPlatform.latest_charge as string,
);

const transfer = await StripeClient.transfers.retrieve(
  latestCharge.transfer as string,
);


const payment = await StripeClient.charges.retrieve(
  transfer.destination_payment as string,
    undefined,
    {
        stripeAccount: transfer.destination as string,
      },
  );

1. Create a customer and then update the charge with the relevant customer ID and metadata. The customer must belong to the connected account and not the platform for the data to pass, and apps to synchronize.

const customer = await StripeClient.customers.create(
      {
        email: `jenny.rosen@example.com`,
        name: "Jenny Rosen",
	 address.city: "Brothers"
	 Address.state: "Oregon"
	 address.country: "USA"
	 address.line1: "27 Fredrick Ave"
	 address.postal_code: "97712"
       	 metadata: {
 	   platform_customer_ID: "K-123456"
	 },
      },
      {
        stripeAccount: accountId,
      },
    );
    const payment = await StripeClient.charges.update(
      id,
      {
        customer: customer.id,
        metadata: {
          product_name: "Creative writing course for PMs",
          platform_product_ID: "P-123456"
          platform_order_ID: "O-123456"
        },
      },
      {
        stripeAccount: accountId,
      },
    );

The embedded integrations accesses all payment, customer, and product data stored with Stripe. You can pass optional platform-specific data to the App using the below metadata schema.