Private preview

Embedded Stripe Apps integration guide Private preview

Use embedded components for Stripe Apps to allow your customers to manage payments data in third party applications.

Customers expect their payments data to be readily available in the tools they’re already using to complete their business workflows. Embedded components for Apps allow your customers to use third party applications in Stripe.

With embedded components for Apps, you can embed integrations built for Stripe into your platform, and allow your customers to use their preferred third party applications without leaving Stripe. Use prebuilt UI components that sync data directly with applications such as QuickBooks and Xero.

Integrate with Connect embedded components

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.

Select the app to integrate

Stripe supports the following app integrations.

Set up app installation

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.

Command Line

Select a language

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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

app-install.js

Select a language

JavaScript

React

No results

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

This embedded component supports the following parameters:

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

index.html

Select a language

HTML and JavaScript

React

No results

<div id="app-install-container"></div>

index.js

Select a language

HTML and JavaScript

React

No results

// 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);

Set up app settings

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

app-viewport.js

Select a language

JavaScript

React

No results

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:

Customise for Connect destination on behalf of (OBO)

To ensure that your selected app properly processes transaction data, you must update the destination charge on the connected account by using the standardised data schema. It’s crucial that your platform sends at least a Customer object (specifically the customer ID) with each charge event.

This requirement is important because the charge.updated event might be sent multiple times for a single transaction. However, the third-party app only reads and processes events that include a customer ID. Always include the customer ID in the payload to confirm that the app processes the corresponding transaction. You have three scenarios that require you to update your destination charge:

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

QuickBooks Sync by Acodei also requires charge updates with refund amounts written to metadata.

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

const customer = await StripeClient.customers.create(
 {
 email: `jenny.rosen@example.com`,
 name: "Jenny Rosen",
 address: {
 city: "Brothers",
 state: "Oregon",
 country: "USA",
 line1: "27 Fredrick Ave",
 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,
 },
 );

Direct charges

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.

Interested in the preview of embedded components for Apps?

Enter your email to request access.