Fully embedded Connect platform integration

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.

You can request additional capabilities, such as specific payment methods, after the account onboards.

Call /v1/accounts with the following parameters:

• country of the account
• controller.stripe_dashboard.type = none
• request the card_payments and transfers capabilities

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d country=US \
  -d "controller[stripe_dashboard][type]"=none \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true

{
  "id": 
"{{CONNECTED_ACCOUNT_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 accounts access their accounts, as well as core payments functionality, directly in your platform and don’t have access to a Stripe-hosted Dashboard. You must provide access to certain features through your website.

Your integration must include the following embedded components:

• Account onboarding
• Account management
• Notification banner
• Documents (when Stripe collects Stripe fees directly from connected accounts)

Your integration must also provide a way to respond to disputes with evidence on individual payments. You can implement this using our API or an embedded component (Payments, Payment details, or Disputes for a payment).

We recommend that you provide a way to allow connected accounts to add money if needed to avoid a negative balance and prevent business disruptions. You can implement this using an embedded component (Balances or Payouts).

You can also add additional embedded components or build your own UIs using our APIs.

Make sure you set up embedded components before onboarding 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:

1. 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.
2. To determine the information that Stripe requires from a connected account, retrieve the account’s requirements property.
3. Collect prefillable information.
4. Record the information on the account by calling Update Account.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d business_type=individual \
  --data-urlencode email="jenny.rosen@example.com" \
  -d "individual[first_name]"=Jenny \
  -d "individual[last_name]"=Rosen \
  --data-urlencode "individual[email]"="jenny.rosen@example.com" \
  -d "individual[address][line1]"="354 Oyster Point Blvd" \
  -d "individual[address][city]"="South San Francisco" \
  -d "individual[address][state]"=CA \
  -d "individual[address][postal_code]"=94080 \
  -d external_account=
{{BANK_ACCOUNT_TOKEN_ID}}

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_onboarding in the components parameter.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[account_onboarding][enabled]"=true \
  -d "components[account_onboarding][features][external_account_collection]"=true

After creating the Account Session and initializing ConnectJS, you can render the Account onboarding component in the front end:

// Include this element in your HTML
const accountOnboarding = stripeConnectInstance.create('account-onboarding');
accountOnboarding.setOnExit(() => {
  console.log('User exited the onboarding flow');
});
container.appendChild(accountOnboarding);

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_submitted field on the Account changes to true. Check the status by looking for details_submitted: true in the account.updated event body in your webhook handler or by retrieving the Account. If details_submitted 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.

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_banner in the components parameter.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[notification_banner][enabled]"=true \
  -d "components[notification_banner][features][external_account_collection]"=true

Render the notification banner component

// Include this element in your HTML
const notificationBanner = stripeConnectInstance.create('notification-banner');
container.appendChild(notificationBanner);

// Optional:
// notificationBanner.setCollectionOptions({
//   fields: 'eventually_due',
//   futureRequirements: 'include',
// })

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_management in the components parameter.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[account_management][enabled]"=true \
  -d "components[account_management][features][external_account_collection]"=true

Render the account management component

// Include this element in your HTML
const accountManagement = stripeConnectInstance.create('account-management');
container.appendChild(accountManagement);

// Optional:
// accountManagement.setCollectionOptions({
//   fields: 'eventually_due',
//   futureRequirements: 'include',
// })

This component allows an account to update their account details, respond to compliance requirements that are due, and update their authentication credentials.

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.updated event. A connected account is ready to receive payments when its charges_enabled 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. If you choose to build and maintain a completely API-driven custom payment list instead, you can still enable refunds and disputes using either the Payment details component, the Disputes for a payment component, or our APIs.

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:

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[payments][enabled]"=true \
  -d "components[payments][features][refund_management]"=true \
  -d "components[payments][features][dispute_management]"=true \
  -d "components[payments][features][capture_payments]"=true \
  -d "components[payments][features][destination_on_behalf_of_charge_management]"=false

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:

// Include this element in your HTML
const payments = stripeConnectInstance.create('payments');
container.appendChild(payments);

// Optional: specify filters to apply on load
// payments.setDefaultFilters({
//   amount: {greaterThan: 100},
//   date: {before: new Date(2024, 0, 1)},
//   status: ['partially_refunded', 'refund_pending', 'refunded'],
//   paymentMethod: 'card',});

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:

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[payouts][enabled]"=true \
  -d "components[payouts][features][instant_payouts]"=true \
  -d "components[payouts][features][standard_payouts]"=true \
  -d "components[payouts][features][edit_payout_schedule]"=true \
  -d "components[payouts][features][external_account_collection]"=true

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

// Include this element in your HTML
const payouts = stripeConnectInstance.create('payouts');
container.appendChild(payouts);

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, use direct charges.

Stripe assesses payment transaction fees to your platform when controller.fees.payer 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.

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Pay</button>
    </form>
  </body>
</html>

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d mode=payment \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

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’re 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.dispute.created 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. You must update these links before creating an account session or an account link in livemode.

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.

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

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.