Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Get started with Connect
Integration fundamentals
    Make API calls for connected accounts
    Integration recommendations
    Migrate to a supported configuration
    Configure the behavior of connected accounts
    Listen for updates
    Testing
    Accounts v2 API overview
Example integrations
Account management
Onboard accounts
Configure account Dashboards
Work with connected account types
Payment processing
Accept payments
Pay out to accounts
Platform administration
Manage your Connect platform
Tax forms for your Connect platform
HomePlatforms and marketplacesIntegration fundamentals

Configure the behavior of connected accountsPublic preview

Learn how to configure your connected accounts using the Accounts v2 API.

You define the interactions between your platform, connected accounts, and Stripe, such as funds flows and loss liability, by configuring your connected accounts. Set up your integration to configure them by specifying values for certain properties when it creates the corresponding Accounts v2 objects. For example, properties in the defaults.responsibilities hash assign liability for negative balances on your connected accounts and specify how Stripe collects payment fees.

The values you assign to your connected account properties also affect other aspects of your integration. For example, responsibility for verifying identity information is assigned to Stripe or your platform based on negative balance liability and connected accounts’ access to Stripe Dashboards.

Note

Responsibilities and the dashboard property in Accounts v2 correspond to controller properties in Accounts v1. This document includes a map of controller properties to Accounts v2 properties.

Set responsibilities

You must define defaults.responsibilities properties when you add the Merchant configuration to an account. You can’t update their values later.

PropertyDescriptionValues
defaults.responsibilities.fees_collectorDefines how Stripe collects payment fees for direct charges on the connected account. (For destination or separate charges, Stripe always collects fees from your platform.)
  • application: Your platform collects application fees from the connected account, and Stripe collects payment fees from your platform.
  • stripe: Stripe collects payment fees directly from the connected account.
defaults.responsibilities.losses_collectorAssigns responsibility for negative balances incurred by the connected account.
  • application: Your platform is responsible for negative balances and manages risk for the connected account.
  • stripe: Stripe is liable for the connected account’s negative balances. Your platform is still liable for negative balances on your platform account.

Responsibilities are subject to the following restrictions:

  • If you set losses_collector to application, then you must also set fees_collector to application.
  • If you use destination charges with an Account, we recommend that you set both losses_collector and fees_collector to application.

For more information about supported configurations, see Integration recommendations.

Set Dashboard access

You must set the dashboard property value (if its existing value is null) when you add the Merchant configuration to an account. You must also set the dashboard value (if its existing value is null) when you request the stripe_transfers feature for the Recipient configuration on an account. Choose from the following values:

  • express: The connected account can access the Stripe Express Dashboard, which offers limited functionality. You can customize its appearance with your platform’s branding.
  • full: The connected account can access the full Stripe Dashboard. The full Stripe Dashboard lets your connected accounts view and manage their finances and reports.
  • none: The connected account can’t access either Stripe Dashboard. Your platform must provide all Stripe-related functionality.

Regardless of the dashboard setting, your platform can use Connect embedded components to provide your connected accounts with similar functionality in a custom interface.

Dashboards are subject to the following restrictions:

  • If you set dashboard to express, then you must also set both losses_collector and fees_collector to application.
  • If you set dashboard to full, then you must also set both losses_collector and fees_collector to stripe.

For more information about supported configurations, see Integration recommendations.

Collect Know Your Customer (KYC) requirements

Responsibility for collecting KYC requirements is based on the defaults.responsibilities.losses_collector and dashboard values. In most configurations, Stripe is responsible for collecting KYC requirements from your connected accounts. Your platform is responsible only when you set defaults.responsibilities.losses_collector to application and dashboard to none.

Note

Configure platform responsibility for requirements collection only if you’re prepared to manage the operational complexity required to verify requirement information and maintain compliance with any requirement updates.

Accounts v1 controller property map

The settings described in this document correspond to Accounts v1 controller properties as follows:

Accounts v1 PropertyAccounts v2 PropertyDescription
controller.fees.payerdefaults.responsibilities.fees_collectorDefines who collects payment fees for direct charges on the connected account. (For destination charges, Stripe always collects fees from your platform.)
controller.losses.paymentsdefaults.responsibilities.losses_collectorDefines responsibility for negative balances incurred by the connected account.
controller.requirement_collectionN/AIn Accounts v2, this responsibility is calculated based on the losses_collector and dashboard values.
controller.stripe_dashboard.typedashboardSpecifies connected account access to Stripe Dashboards.
Was this page helpful?
YesNo
  • Need help? Contact Support.
  • Join our early access program.
  • Check out our changelog.
  • Questions? Contact Sales.
  • LLM? Read llms.txt.
  • Powered by Markdoc