Fully embedded Connect platform integration
Provide Connect features to your connected accounts through your own website.
Connect embedded components let you add Stripe-managed functionality to a custom interface that you provide to your connected accounts. They can perform payment-related activities there instead of through the Stripe Dashboard. In a fully embedded integration:
- Connected accounts access Stripe-related data, forms, and notifications through embedded components in your platform’s application. They don’t have access to a Stripe Dashboard.
- Stripe manages credit and fraud risk on your connected accounts. For any risk or compliance actions, we communicate directly with connected accounts and they respond by interacting with embedded components.
- Stripe email notifications direct your connected accounts to embedded components on your website to review information or take required action. You must provide Stripe with the URLs for those components.
View the demo site
We’ve built a complete demo site for our fictitious business, Furever. Furever is a platform providing software for pet-groomers that allows their users to collect payments. In this demo, you can interact with many embedded components, including account onboarding and account management.
Before you begin
Before you can build an embedded integration, complete the following prerequisites:
- Register your platform.
- Add business details to activate your account.
- Complete your platform profile.
- Customize your brand settings. Add a business name, icon, and brand color.
You must also decide whether your platform will own pricing, in which case Stripe collects payment fees from your platform and you bill your connected accounts. Otherwise, Stripe owns pricing and collects payment fees directly from your connected accounts.
Create a connected account
The following example creates an account where Stripe manages risk, controls pricing, and assumes responsibility for account onboarding requirements. Your platform uses embedded components and isn’t liable for negative balances. Your connected accounts don’t have access to Stripe-hosted dashboards.
Note
Because Stripe controls pricing in this example, you must integrate the Documents embedded component. In addition, Stripe notifies connected accounts by email when their tax invoices or 1099s are ready for download. If you create accounts where your platform controls pricing, the Documents component isn’t required, and Stripe doesn’t send notifications to connected accounts about tax invoices or 1099s.
You can request additional capabilities, such as specific payment methods, after the account onboards.
Call /v1/accounts with the following parameters:
country
of the accountcontroller.
=stripe_ dashboard. type none
- request the
card_
andpayments transfers
capabilities
{ "id":
, "object": "account", "controller": { "type": "application", "is_controller": true, "losses": {"payments": "stripe"}, "fees": {"payer": "account"}, "requirement_collection": "stripe", "stripe_dashboard": { "type": "none", }, }, "type": "none", ... }"{{CONNECTED_ACCOUNT_ID}}"
Set up embedded components
Connected accounts access their accounts, as well as core payments functionality, directly in your platform and don’t have access to a Stripe-hosted Dashboard, so you must provide access through your site.
Your integration must include the following embedded components:
- Account onboarding component
- Account management component
- Notification banner component
- Documents component (when Stripe collects Stripe fees directly from connected accounts)
For any other optional components, you can use our embedded components or build your own UI.
Make sure you set up embedded components before onboarding connected accounts.
Onboard connected accounts
Stripe uses an Account Session to express your intent to provide embedded component access to the connected account. Using an Account Session, the embedded account onboarding component collects all required information based on your requested capabilities.
Prefill the account
The embedded account onboarding component collects all required information based on your requested capabilities.
You can streamline the onboarding flow for your users by prefilling account fields with known information before you create an Account Session. Prefill as much account information as possible, including company, individual, and external account information, following these steps:
- Review the required verification information docs to learn more about how the combination of countries and capabilities you select for connected accounts affects their requirements.
- To determine the information that Stripe requires from a connected account, retrieve the account’s requirements property.
- Collect prefillable information.
- Record the information on the account by calling Update Account.
After the connected account completes onboarding through the Account Onboarding embedded component, your platform can no longer update certain information such as payout accounts or legal entity information. The connected account must make any updates to that information because the platform isn’t responsible for negative balances.
Onboard users through the embedded onboarding component
Connected accounts must go through onboarding and provide required information to enable charges and payouts. To onboard a connected account, host the onboarding embedded component on your site and direct new accounts there.
Create an Account Session
When creating an Account Session, enable account management by specifying account_
in the components
parameter.
After creating the Account Session and initializing ConnectJS, you can render the Account onboarding component in the front end:
Present the onboarding flow to the account’s primary owner. The primary owner sets up authentication with Stripe, and is the user who can edit the account details and respond to risk interventions. The connected account has only a single set of authentication credentials with Stripe. The user with authentication credentials can authenticate using one-time SMS codes to perform more sensitive actions like updating bank accounts for payout destinations or providing updated legal entity information.
Listen for onboarding events
As the account proceeds through onboarding, account.updated events are also sent to your configured Connect webhooks. When the account finishes submitting their details, the details_
field on the Account changes to true. Check the status by looking for details_
in the account.
event body in your webhook handler or by retrieving the Account. If details_
is false, show the embedded onboarding component again. If the account submitted some information, the embedded onboarding component skips it and only collects the unsubmitted requirements.
When a connected account submits their details and completes the onboarding flow, the embedded onboarding component calls the onExit
handler that you set when you render the component. Use the callback to direct the account to their next action. If you don’t set an exit handler, or take action inside of the handler, the account sees a completion message without a clear next step.
Request additional capabilities (optional)
Your platform can continue to request additional capabilities after onboarding a connected account. For example, you must request the capabilities for any payment methods you want to enable for an account.
If any requested capabilities require additional information, the connected account receives a notification through the embedded notification banner.
Handle ongoing compliance and risk updates
Because Stripe manages credit and fraud risk for your connected accounts, your accounts must be able to see and respond to alerts from Stripe. To facilitate that, your platform must integrate the notification banner and account management embedded components. For more information about how Stripe supports your connected accounts through these components, see Embedded Connect support.
Embed the notification banner
Stripe uses the notification banner embedded component to notify connected accounts of outstanding compliance requirements and other risk-related requests. Responding to these notifications allows an account to remain compliant so it can process payments and receive payouts. If there are no outstanding notifications, the embedded notification banner doesn’t render.
Integrate the notification banner in a highly visible and easily accessible location on your website. For example, you can integrate it at the top of your payments page.
Create an Account Session
When creating an Account Session, enable notification banner by specifying notification_
in the components
parameter.
Render the notification banner component
To respond to a banner notification, the account can click a button in the notification. You don’t need to redirect them to the account management embedded component.
Embed account management
Stripe requires the account management embedded component when managing risk. Integrate the component in your website where an account updates their settings or profile.
Create an Account Session
When creating an Account Session, enable account management by specifying account_
in the components
parameter.
Render the account management component
This component allows an account to update their account details, respond to compliance requirements that are due, and update their authentication credentials.
Integrate payments
Set up the payments integration after integrating required embedded components. You can add the payments and payout embedded components to your platform or build your own workflows.
Configure Connect webhooks and listen for the account.
event. A connected account is ready to receive payments when its charges_
property is true.
Integrate embedded payments and payouts
Add the payments and payouts embedded components to your platform before building your payments integration. That way, an account can easily access and manage their core payment workflows.
The payments component shows a list of the connected account’s payments, and includes filtering and individual payment detail views. An account can issue refunds and respond to disputes with evidence on individual payments through this component.
Create an Account Session
When creating an Account Session, enable the payments embedded component by specifying payments
in the components
parameter. You can turn on or off an individual feature of the payments component by specifying the features
parameter under payments
:
Your connected accounts can view the complete set of information about direct charges. They can also manage refunds, manage disputes, and capture payments if you enable the corresponding features when creating an account session.
Render the payments component
After creating the account session and initializing ConnectJS, you can render the payments component in the front end:
The payouts component shows the connected account’s recent payouts, current balance, and when funds will become available.
When creating an Account Session, enable the payouts embedded component by specifying payouts
in the components
parameter. You can enable or disable individual features of the payouts component by specifying the features
parameter under payouts
:
After creating the account session and initializing ConnectJS, you can render the payouts component in the front end:
For an immersive guide to implementing embedded components, follow the Connect embedded components integration quickstart.
Accept a payment
If your connected accounts transact directly with customers, Stripe strongly recommends using direct charges.
Stripe assesses payment transaction fees to your platform when controller.
is not set to account
for the Account. In turn, you’re responsible for charging payment processing fees on your connected accounts. You can specify a value for the application fee on each payment to automatically take fees from connected accounts without having to build it into your integration.
We recommend using Stripe Checkout, a prebuilt Stripe-hosted page, to accept payments. Checkout supports multiple payment methods and automatically shows the most relevant ones to your customer.
You can also use the Payment Element, a prebuilt UI component you can embed to accept additional payment methods with a single integration.
Set up email communications to connected accounts
Stripe communicates with your connected accounts on your behalf to manage risk and ensure ongoing compliance. You can customize and brand these email communications with your own email domain and platform branding.
We send the following emails to your connected accounts:
- Account emails verify an account’s information, such as additions or changes to an email address, phone number, or bank account.
- Compliance emails notify accounts to provide required information. Stripe often needs to collect further information to maintain compliance with our financial partners.
- Risk emails notify accounts when they are under a risk review. These emails often provide instructions on how to submit information to resolve a risk action; for example, to remove a pause on payouts.
- Tax emails (only when Stripe collects Stripe fees directly from connected accounts) notify users when their tax invoices or 1099s are ready to download.
If you want to send any other payments-related emails to your connected accounts, you must send them yourself. For example, to send emails for new disputes, listen for the charge.
event on a connected account. When that event occurs, use the Disputes API to get the details and email them to the account.
You must update your Connect settings with the URLs of your payments and account workflows so Stripe’s email communications can include links for your accounts to respond.
Handle redirects from email links
Emails sent by Stripe that contain a call to action need to include a link to that action. For example, if we send an email directing action on a connected account, it must include a link to your Account management component.
Before you can create a live mode Account Session, you must provide the URLs where you have integrated the embedded components into your website. Configure the sending email domain and embedded component URLs in the Site links section of your platform’s Connect settings.
Note
Test mode environments use the same URLs as live mode.
For embedded components integrated in your site, select Yes and enter the URL of the page that hosts the component. For any actions not handled by an embedded component, select No and enter the URL of the page on your site where the account can perform the action. After entering the URLs, test them to verify that they open the right pages.
You must set URLs for the following:
- Notification banner
- Account management
- Payments
- Payouts
- Balances
- Documents (when Stripe collects Stripe fees directly from connected accounts)
When sending an email, Stripe automatically appends the connected account ID to the redirect URL as the stripe_
parameter. Use that parameter to identify the account and verify that they’re authenticated. Set up the route on your server to read the parameters and display the correct embedded component.
For more information about configuring Stripe emails to your connected accounts, see Email communications in embedded Connect integrations
Configure email branding and settings
Stripe can send emails reflecting your platform’s brand settings from your own email domain to your connected accounts. To configure Stripe emails to your connected accounts, visit Emails in your platform Dashboard.
Go live
At this point, you’ve configured your platform integration by doing the following:
- Created connected accounts in the correct configuration
- Integrated embedded components to allow connected accounts to onboard, manage their account, and respond to risk actions through your website
- Set up payments using Direct charges with an application fee
- Set up branded email communications to enable Stripe to communicate with your users for compliance, risk actions, and necessary documents
Test your integration
Test your account creation flow by using the embedded account onboarding integrated in your platform. Test the settings of your payment methods for your connected accounts by logging into one of your test accounts and navigating to the Payment methods settings. Test your checkout flow with your test keys and a test account. You can use our test cards to test your payments flow and simulate various payment outcomes.