Embedded Stripe Apps integration guideBeta
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.
Select the app to integrate
Stripe supports the following app integrations.
App integration | App ID |
---|---|
QuickBooks Sync by Acodei | com.example.acodeistripeapp |
Xero sync by Xero | com.xero.stripeapp |
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_
, and app_
in the components
parameter. You must enable the app you want to render by specifying the features
parameter under allowed_
.
After creating the account session and initializing ConnectJS, you can render the App install component in the front end:
This embedded component supports the following parameters:
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 synchronization states of transactions. Pass the user_
(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.
This embedded component supports the following parameters:
Customize for Connect destination on behalf of (OBO)
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
Field or key name | Format (standard CSV rules apply) | Description | Required | |
---|---|---|---|---|
charges.customer | String (ID) | Stripe Customer ID (belonging to the connected account) attached to a destination Charge object. Transactions don’t sync to apps (such as Xero and QBO) if this field isn’t present. | Required | |
customer.name | String | Customer’s full name* | ||
customer.email | String | Customer’s email address | ||
customer.address.<> | String (multi-field) | Customer’s physical address (can be used for both billing and shipping) | ||
charges. | String (cents integer) | Mirroring charges.amount_refunded | Required by Quickbooks Online sync by Acodei | |
charges. | string | reason for the refund | ||
charges. | true | false | null | Set to true if currency has been converted, for example, if the presentment currency differs from the settlement currency | Required by Quickbooks Online sync by Acodei if using fees_names metadata | |
customer. | String | Customer ID as recorded in the platform’s system* | ||
charges. | String, CSV multiple products | Product IDs as recorded in the platform’s system | ||
charges. | String, CSV multiple products | Product name as recorded in the platform’s system | ||
charges. | String, CSV multiple products | Quantity of each product corresponding to the ID and name array | ||
charges. | String, CSV multiple products | The individual Product value (price and cost) corresponding to the Product ID and name | ||
charges. | String, CSV multiple products | Product tag or category corresponding to the ID and name array | ||
charges. | String | Order ID as recorded in the platform’s system | ||
charges. | String | Charge or transaction ID as recorded in the platform’s system and visible to the business | ||
charges. | String, CSV multiple fees | Name of fees the user is paying (expense) of any kind related to the transaction that aren’t captured in the Charge (for example, credit processing fee or platform fee) If this field is populated, the charges.application_fee is ignored. | ||
charges. | String, CSV multiple fees | Values of fees the user is paying (expense) of any kind related to the transaction that aren’t captured in the charge (for example, the credit processing fee or platform fee) | ||
charges. | String, CSV multiple revenues | Fees (revenues) collected by the business related to this transaction (charge) that aren’t captured in the charge (for example, a convenience fee or tips) | ||
charges. | String, CSV multiple revenues | Values of fees (revenues) collected by the business related to this transaction (charge) (for example, $2 or $1.50 if the transaction were in USD) | ||
charges. | string | Total taxes associated with this transaction (charge) | ||
charges. | String, CSV multiple taxes | Tax type names applied on a transaction allowing for multiple tax types, using an array (for example GST or sales) | ||
charges. | String, CSV multiples taxes | Tax rates applied on a transaction corresponding to specified tax types as a percentage (for example 3% or 1.5% would correspond to 3% GST and 1.5% sales tax) | ||
charges. | string, CSV multiple taxes | Tax values applied on a transaction corresponding to specified tax types in the base currency |
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.
- 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, }, );
- 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, }, );
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.
Field or key name | Format (standard CSV rules apply) | Description |
---|---|---|
customer. | string | Customer ID as recorded in the platform’s system |
payment. | string, CSV multiple products | Product IDs as recorded in the platform’s system, related to this transaction (if different than the Stripe product ID) |
payment. | string, CSV multiple products | Product or service names as recorded in the platforms’ system, related to this transaction (if different than the Stripe product name) |
payment. | string, CSV multiple products | The individual product value (price or cost) corresponding to the ID and name array (if different than the Stripe product value) |
payment. | string | Order ID as recorded in the platform’s system, related to this transaction (charge) |
payment. | string | Charge or transaction ID as recorded on the platform and visible to the user (if different than the Stripe payment ID) |
Other integrations
If you need an integration with other software or any other integration types, contact stripe-apps@stripe.com.