Customize your Connect integration
Beta

Configure onboarding, management, and risk ownership for connected accounts that accept direct payments.

Overview

This guide shows you how to configure a Connect multiparty payments integration where your platform determines payment fees and collects them from your connected accounts using platform pricing tools. Stripe assesses our fees directly to your platform, not to your connected accounts.

When designing your integration, you have several options:

Onboarding UI:
- Hosted: Directs accounts to onboard through a Stripe-hosted onboarding flow.
- Embedded: You integrate the onboarding flow directly into your platform UI.
Account dashboard UI:
- Stripe: Your accounts use the Stripe Dashboard.
- None: You build a custom dashboard using Embedded components in your platform UI. To use embedded account dashboards, you must also use embedded onboarding.
Risk ownership and loss liability:
- Stripe: Stripe manages risk and takes responsibility for negative balances on your connected accounts.
- Platform: You manage risk and take responsibility for negative balances on your connected accounts. To use platform liability, you must also use Stripe account Dashboards.

These integration options are most suitable for platforms that enable their connected accounts to accept payments directly. If you’re integrating payments as a marketplace platform, follow the Collect payments then pay out guide.

Example integration

We’ve built a complete demo site for our fictitious business, Furever, that uses embedded onboarding and embedded account dashboards. Furever is a platform that allows pet groomers to collect payments. In this demo, you can interact with the embedded components that handle account onboarding and management.

Configure a customized integration

Learn how to configure your integration by selecting the applicable options:

Connected account onboarding

In Stripe, connected accounts represent the businesses that pay your platform for its services. When you create a connected account, you must onboard it by collecting and verifying certain information.

Hosted Connect onboarding is a Stripe-hosted, redirect-based method that allows Stripe to manage identity verification and handle requirement updates using a localized form.

Connected account dashboards

Connected accounts can access features through the Stripe Dashboard or through a custom dashboard embedded in your application.

With Stripe Dashboards, connected accounts create a Stripe Dashboard login to view payments, manage refunds, and perform additional account management workflows.

Connected account risk ownership and loss liability

When Stripe owns risk and loss liability, we manage credit and fraud risk for your connected accounts, including applying interventions and remediating fraud. If your connected accounts don’t use the Stripe Dashboard, your application must embed components that let them see and respond to alerts from Stripe.

Prerequisites

Register your platform.
Add business details to activate your account.
Complete your platform profile.
Customize your brand settings. Connect onboarding requires that you add a business name, icon, and brand color.

Create and onboard connected accounts

Call /v1/accounts with the following specifications:

unified_accounts_beta=v1 header
Include your API version in the beta header. You can find your API version on the Developers page of your Stripe Dashboard.

If you’ve already collected information for your connected accounts, you can prefill that information on the account object. You can prefill any account information, including personal and business information, external account information, and more.

Connect Onboarding doesn’t ask for the prefilled information. However, it does ask the account holder to confirm the prefilled information before accepting the Connect service agreement.

When testing your integration, prefill account information using test data.

Don’t specify type for the account; it’s not required in this beta.

Command Line

curl https://api.stripe.com/v1/accounts \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Version: 2023-10-16; unified_accounts_beta=v1" \
  -d country=US

The response to a successful API call is the account information and an account ID. Store the account ID in your database. When making requests for the connected account, you authenticate by passing its account ID in the Stripe-Account header.

Your platform account is preconfigured with the Connect configuration that you’ve set up with a member of your Stripe deployment team. You can see your platform’s Connect configuration on the Connect setup page in Connect Settings. If you see an account object with an unexpected configuration, contact your Stripe deployment team or Stripe Support.

# Example response
{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "controller": {
    "type": "application",
    "is_controller": true,
    "application": {
      "loss_liable": false,
      "pricing_controls": true,
      "onboarding_owner": false
    },
    "dashboard": {
      "type": "full"
    },
  },
  "type": "standard",
  ...
}

Create an account link

Use the account ID returned in the create response to create an account link. The link allows the account holder to complete the onboarding process with Connect Onboarding.

If you want to prefill information, you must do so before generating the account link.

Command Line

curl https://api.stripe.com/v1/account_links \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account={{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding

Send the account to the account link URL

The response to your Account Links request includes a value for the key url, which opens the Connect Onboarding flow for the associated account. URLs from the Account Links API are temporary and only usable one time, because they grant access to the account holder’s personal information.

Security tip

Don’t email, text, or otherwise send account link URLs outside of your platform application. Instead, provide them to the authenticated account holder within your application.

Handle the account returning to your platform

Connect Onboarding requires you to pass both a return_url and a refresh_url so it can handle all cases where Stripe redirects the user to your platform. You must implement both pages.

You can use HTTP for your return_url and refresh_url while in test mode, but live mode only accepts HTTPS. Before going live, replace testing URLs with HTTPS URLs.

return_url

When an account completes the Connect Onboarding flow, Stripe redirects it to the return_url. That doesn’t mean the account has fulfilled all of its requirements—it only means that the account entered and exited the flow properly.

Stripe doesn’t pass the onboarding state through this URL. After Stripe redirects the account to your return_url, check the state of their details_submitted property by doing either of the following:

Listening to account.updated webhooks
Calling the Accounts API and inspecting the returned object

refresh_url

Stripe redirects your user to the refresh_url in these cases:

The account uses the link after the link expires.
The account uses the link more than once, which can happen when they refresh the page or click back or forward in the browser.
Your platform no longer has access to the account.
The account is rejected.

At your refresh_url, trigger a method on your server to call Account Links with the same parameters. Then redirect the account to the new link to retry the Connect Onboarding flow.

Handle accounts that haven’t completed onboarding

Stripe can redirect an account to your return_url when they fail to complete the onboarding process. Retrieve the account using the /v1/accounts endpoint and check for charges_enabled. If charges aren’t enabled, then they didn’t complete onboarding. In that case, provide UI prompts to allow them to continue the process with a new account link. To see if they’ve completed the onboarding process, you can check the state of the details_submitted property on the account.

After the account completes the onboarding process and is active, you can start creating direct charges for them.

Accept payments

Stripe recommends the direct charge implementation when a customer is transacting directly with the business/user on your platform.

Stripe assesses payment transaction fees to your platform when the controller["application"]["pricing_controls"] property for the Account is true. You’re responsible for assessing your users for payment processing fees. You can specify a value for the application fee on each payment or use Platform Pricing Tools 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.

Create a Checkout Session Client-side Server-side

A Checkout Session controls what your customer sees in the Stripe-hosted payment page such as line items, the order amount and currency, and acceptable payment methods. When performing direct charges, Checkout uses the connected account’s branding settings. See the Customize branding section for more information.

Unlike destination charges and separate charges and transfers, connected accounts are responsible for handling disputes on direct charges—it’s not the responsibility of the platform.

Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.

checkout.html

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

On your server, make the following call to the Stripe API. After creating a Checkout Session, redirect your customer to the URL returned in the response.

Command Line

curl https://api.stripe.com/v1/checkout/sessions \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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"

line_items—Represents items that your customer is purchasing and that show up in the hosted user interface.
success_url—This argument redirects a user after they complete a payment.
cancel_url—This argument redirects a user after they click cancel.
Stripe-Account—This header indicates a direct charge for your connected account. With direct charges, the connected account is responsible for Stripe fees, refunds, and chargebacks. The connected account’s branding is used in Checkout, which allows their customers to feel like they’re interacting directly with the merchant instead of your platform.
(Optional) payment_intent_data[application_fee_amount]—This argument specifies the amount your platform plans to take from the transaction. After the payment is processed on the connected account, the application_fee_amount is transferred to the platform and the Stripe fee is deducted from the connected account’s balance.

Handle post-payment events Server-side

Stripe sends a checkout.session.completed event when the payment completes. Use a webhook to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes. Some payment methods also take 2-14 days for payment confirmation. Setting up your integration to listen for asynchronous events enables you to accept multiple payment methods with a single integration.

In addition to handling the checkout.session.completed event, we recommend handling two other events when collecting payments with Checkout:

Event	Description	Next steps
checkout.session.completed	The customer has successfully authorized the payment by submitting the Checkout form.	Wait for the payment to succeed or fail.
checkout.session.async_payment_succeeded	The customer’s payment succeeded.	Fulfill the purchased goods or services.
checkout.session.async_payment_failed	The payment was declined, or failed for some other reason.	Contact the customer through email and request that they place a new order.

These events all include the Checkout Session object. After the payment succeeds, the underlying PaymentIntent status changes from processing to succeeded.

Set up fees to monetize payments

Your platform can use pricing tools to automatically collect application fees for transactions made on behalf of your connected accounts. After you set up platform pricing tools for payments, you don’t need to pass the application_fee_amount parameter. If you do pass the application_fee_amount, it supersedes the configured rate.

Handle refunds for direct charges

You can issue refunds on behalf of a connected account.

When creating a refund, Stripe doesn’t refund the application fee to the connected account by default. To refund application fees to a connected account, pass the refund_application_fee value as true.

Command Line

curl https://api.stripe.com/v1/refunds \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}
" \
  -d charge={{CHARGE_ID}} \
  -d refund_application_fee=true

Paying out to accounts

Automatic payouts

Stripe creates automatic payouts from the connected account balance to the connected bank account. You can set the payout schedule of the connected account using the Accounts API. To help with reconciliation, you can get a list of all transactions included in an automatic transfer by using the balance history endpoint and the payout parameter.

Payouts are typically automated and handled asynchronously when a Connect webhook receives the payout.created or payout.paid event.

Command Line

curl -G https://api.stripe.com/v1/balance_transactions \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}
" \
  -d payout={{PAYOUT_ID}} \
  -d limit=100

Manual payouts

Your platform can also create manual payouts from the connected account balance to the connected bank account using the payouts endpoint. Because you specify the amount of a manual payout, Stripe has no record of the transactions associated with it. Your platform must manage that information.

Command Line

curl https://api.stripe.com/v1/payouts \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1000 \
  -d currency=usd

Configure webhooks

After payments complete, you must handle any necessary fulfillment. For example, a store builder must alert the business to send the purchased item to the customer. In your Dashboard, configure a webhook endpoint for events from your Connect applications.

Your platform configures both account and Connect webhooks. Account webhooks capture events that occur on the platform account, such as payouts to the platform’s bank account. Connect webhooks capture events on connected accounts, such as account updates, payments, refunds, and payouts to a connected bank account.

Connect webhooks contain an account property to identify the connected account by ID.

A test mode Connect webhook endpoint receives only test mode events. However, a production Connect webhook endpoint receives both live and test mode events. To distinguish between them, check each event’s livemode property.

To properly retrieve events, webhook endpoints must have a specific version and beta header set. Use the webhooks API to create webhooks with the same API version and beta header as your account create calls. That allows you to identify accounts created using the updated /v1/accounts API for this beta.

Command Line

curl https://api.stripe.com/v1/webhook_endpoints \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "url"="https://example.com/webhook/endpoint" \
  -d "connect"="true" \
  -d "api_version"="2020-08-27; unified_accounts_beta=v1" \
  -d "enabled_events[]"="account.updated"

Testing

By default, Stripe provides both test and live mode for all Stripe accounts. Test mode includes a separate set of data and API keys. We recommend using test mode to build your integration. When you’re ready to go live, replace your test keys with your live keys.

Test the hosted account onboarding flow by creating connected accounts directly from the Dashboard.

Test your Payment methods settings 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.

Guides

The Stripe testing guide provides test card numbers to simulate successful and failed transactions, disputes, bank accounts, and more.
The Connect testing guide provides resources specific to Stripe Connect, including identity verification.
The Integration Security Guide provides information about PCI compliance, secure connections, and other security topics.

Access to these Connect integrations is currently limited to beta users. To request access, sign in. Register for a Stripe account if you don’t have one.

Customize your Connect integrationBeta

Overview

Example integration

Configure a customized integration

Connected account onboarding

Connected account dashboards

Connected account risk ownership and loss liability

Prerequisites

Create and onboard connected accounts

Create an account link

Send the account to the account link URL

Security tip

Handle the account returning to your platform

return_url

refresh_url

Handle accounts that haven’t completed onboarding

Accept payments

Create a Checkout Session Client-side Server-side

Handle post-payment events Server-side

Set up fees to monetize payments

Handle refunds for direct charges

Paying out to accounts

Automatic payouts

Manual payouts

Configure webhooks

Testing

Guides

Customize your Connect integration
Beta