Configure the behavior of connected accounts

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.

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.

Application fee behavior

Fee collection and reporting for direct charges differs based on your pricing model and how you configure fee responsibility. If you use application fees to monetize payment processing for your connected accounts:

• If you set the fee collector to stripe in Accounts v2 or the fee payer to account in Accounts v1, Stripe deducts its processing fee and your application fee from the payment, then pays you your share. Set the application fee amount to include only your fee.
• If you set the fee collector to application , you collect the payment and fees, then pay Stripe its processing fee. Set the application fee amount to include both your fee and the Stripe processing fee.

For example, if the Stripe processing fee is 1.00 and your fee is an additional 1.50, for a total cost to the connected account of 2.50:

• If Stripe collects the fees, set the application fee to 1.50. Stripe deducts its processing fee separately.
• If your platform collects the fees, set the application fee to 2.50 so it covers both fees.

Changing your pricing model

If you change your pricing model or fee collector configuration, you might charge your connected accounts too much or too little. Make sure your connected account configuration applies processing costs as you intend by reviewing your application fees and pricing model before you set or make changes to your responsibilities.

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.

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. You can check the configuration by looking at defaults.responsibilities.requirements_collector, which can be stripe or application.

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: