# Account management

Show account details and allow them to be edited.

Account management renders a UI component for connected accounts to view and proactively edit their account details. Connected accounts can view and edit account information such as personal or business information, public information, and bank accounts they use for payouts.

Account management isn’t optimized for collecting missing account information, and doesn’t handle [risk verifications](https://docs.stripe.com/connect/handling-api-verification.md#handle-risk-verifications). For those use cases, consider using [account onboarding](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md) or the [notification banner](https://docs.stripe.com/connect/supported-embedded-components/notification-banner.md).

Note: The following is a preview/demo component that behaves differently than live mode usage with real connected accounts. The actual component has more functionality than what might appear in this demo component. For example, for connected accounts without Stripe dashboard access (custom accounts), no user authentication is required in production.

## Requirements collection options

When a connected account has outstanding [requirements](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-requirements), account management prompts them to update their information. It always collects `currently_due` requirements, and you can use the `collectionOptions` attribute to also request any of the following:

- `eventually_due` requirements
- [Future requirements](https://docs.stripe.com/connect/handle-verification-updates.md)
- Granular [requirement restrictions](https://docs.stripe.com/connect/supported-embedded-components/account-management.md#requirement-restrictions)

### Requirement restrictions

When you specify collection options, you can configure granular requirement restrictions as `only` or `exclude`. Both options accept an array of strings representing required properties as they appear in `requirements.entries[].description` for v2 Accounts and the various requirement arrays for v1 Accounts. For details about which requirements apply to your connected accounts, see [Required verification information](https://docs.stripe.com/connect/required-verification-information.md).

Think of the options as filters, where `exclude` filters out matching account requirements, and `only` acts as an intersection between the account requirements and the specified values. They also support wildcard matching using `*` and relationship prefixes.

For example, if you have a connected account with several owners, you can collect the address information for all owners by specifying `only: ["owners.address.*"]`.

A person can have multiple relationships associated to them, and relationships can be assigned to multiple persons. Therefore, when you leverage relationship prefixes, they apply to all persons on the account with the specified relationship. This is especially useful in situations where you don’t know a specific person’s ID, but do know their relationship.

Important considerations:

- Accounts still need to satisfy all KYC requirements in order to have capabilities enabled. The `exclude` option doesn’t remove a requirement, it only prevents collection at the time. The information must still be collected.
- These restrictions only apply within embedded components. They don’t affect accounts using other types of dashboards.
- This feature is intended for building improved user experiences, not for preventing accounts from accessing information.

#### only requirement restriction

This option scopes collection to the set of specified requirements that are also outstanding on the account. It’s most commonly used to build a remediation experience, and is particularly useful for requirements that require some form of document upload or identity verification.

This option prevents account onboarding from presenting the standard final summary step. If all of the specified requirements have been provided, the account onboarding component exits immediately.

#### exclude requirement restriction

This option hides the specified fields, which prevents a connected account from providing or editing that information. It only hides fields from the component; it doesn’t remove information requirements. This option is useful when you want to prefill information that you don’t want the connected account to access during onboarding.

For Express accounts, if you want to `exclude` the `business_type` requirement (such as to prevent an account from changing their business type), the account country and capabilities must be set.

## Displayed fields

The [fields](https://docs.stripe.com/connect/required-verification-information.md) that the account management component displays depend on how you configured the connected account—specifically on the connected account country, business type, capabilities and service agreement type. This works similarly to how the [onboarding component](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md) only collects the information that’s required for how the connected account is configured.

## External account collection

Use the [external_account_collection](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_management-features-external_account_collection) feature to control whether the component collects external account information. This parameter is enabled by default. When `external_account_collection` is enabled, [user authentication](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components) is required. You can opt out of Stripe user authentication with the [disable_stripe_user_authentication](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_management-features-disable_stripe_user_authentication) parameter.

## Disable Stripe user authentication

Use the [disable_stripe_user_authentication](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_management-features-disable_stripe_user_authentication) feature to control whether the component requires Stripe user authentication.

- By default, `disable_stripe_user_authentication` is the opposite of the [external_account_collection](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_management-features-external_account_collection) value.
- If you leave `external_account_collection` unset, it defaults to true, so `disable_stripe_user_authentication` defaults to false.

- When `controller.requirement_collection` is `stripe`, both values default to false.

This value can only be true for accounts where `controller.requirement_collection` is `application`.

We recommend implementing 2FA or equivalent security measures as a [best practice](https://docs.stripe.com/connect/risk-management/best-practices.md#prevent-account-take-overs). For account configurations that support this feature, such as Custom accounts, you assume liability for connected accounts if they can’t pay back [negative balances](https://docs.stripe.com/connect/risk-management/best-practices.md#decide-your-approach-to-negative-balance-liability).

### Create an Account Session

When [creating an Account Session](https://docs.stripe.com/api/account_sessions/create.md), enable account management by specifying `account_management` in the `components` parameter.

```curl
curl https://api.stripe.com/v1/account_sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  -d "components[account_management][enabled]=true" \
  -d "components[account_management][features][external_account_collection]=true"
```

### Render the account management component

#### JavaScript

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

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

#### HTML + JS

| Method                 | Type                                                                                                                                              | Description                                                                                                                                                                                           | Default                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `setCollectionOptions` | `{fields: 'currently_due' | 'eventually_due', future_requirements: 'omit' | 'include', requirements: { exclude: string[] } | { only: string[] }}` | Specifies whether to collect `eventually_due` requirements and whether to include `future_requirements`. Specifying `eventually_due` collects both `eventually_due` and `currently_due` requirements. | `{fields: 'currently_due', futureRequirements: 'omit'}` |
| `setOnSectionOpen`     | `({sectionName}: SectionOpenEvent) => void`                                                                                                       | The connected account has opened a section within account management. Use `SectionOpenEvent` to identify the current section, as described below.                                                     |                                                         |

#### React

| React prop          | Type                                                                                                                                               | Description                                                                                                                                                                                                                                                                       | Default                                                 | Required or Optional |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------- |
| `collectionOptions` | `{fields: 'currently_due' | 'eventually_due', futureRequirements?: 'omit' | 'include', requirements?: { exclude: string[] } | { only: string[] }}` | Specifies whether to collect `eventually_due` requirements and whether to include `future_requirements`. Specifying `eventually_due` collects both `eventually_due` and `currently_due` requirements. You can’t update this parameter after the component has initially rendered. | `{fields: 'currently_due', futureRequirements: 'omit'}` | optional             |
| `onSectionOpen`     | `({sectionName}: SectionOpenEvent) => void`                                                                                                        | The component executes this callback function when the connected account opens a section within account management. Use `SectionOpenEvent` to identify the current section, as described below.                                                                                   |                                                         | optional             |

### The SectionOpenEvent object

The `SectionOpenEvent` type is defined in `connect.js`. Every time the connected account opens a section in account management, the section open handler receives a `SectionOpenEvent` object with the following property:

| Name          | Type                                    | Example value      |
| ------------- | --------------------------------------- | ------------------ |
| `sectionName` | `string` (must be a valid section name) | `summary_business` | The unique reference to an account management section. |

#### Section restrictions

- The `SectionOpenEvent` object is only for analytics.
- The event fires only when the connected account opens a section. If the connected account navigates between different views within the same section without closing it, no additional event fires.
- The list of valid `sectionName` values can change at any time, without notice. New values can be added and existing values can be removed.

#### Section names

Each section in account management has one of the following section names.

| Section name                                     | Description                                                                                                                                                        |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `summary_business_type`                          | The connected account can update information related to their business type.                                                                                       |
| `summary_business`                               | The connected account can update information related to their business.                                                                                            |
| `summary_risk`                                   | The connected account can update information related to risk requirements.                                                                                         |
| `summary_additional_terms_of_service`            | The connected account can review and accept additional terms of service.                                                                                           |
| `summary_tax_identification_form`                | The connected account can update information related to their W8/W9 certified tax information.                                                                     |
| `summary_persons`                                | The connected account can update information about each person on their account.                                                                                   |
| `summary_tax_forms`                              | The connected account can update information related to their tax forms.                                                                                           |
| `summary_support`                                | The connected account can update public-facing information related to their business.                                                                              |
| `summary_external_account`                       | The connected account can update information related to their [external account](https://docs.stripe.com/api/accounts/object.md#account_object-external_accounts). |
| `summary_linked_accounts`                        | The connected account can view and manage their linked accounts.                                                                                                   |
| `summary_bank_to_payout_reconciliation_settings` | The connected account can update bank-to-payout reconciliation settings.                                                                                           |