# Notification banner

Show a banner that lists required actions for risk interventions and onboarding requirements.

Renders a notification banner that lists open tasks that can affect a connected account’s status or capabilities. Tasks can involve risk interventions or outstanding requirements for account capabilities, such as accepting payments and payouts. The banner renders only when the connected account must respond to risk interventions or provide currently due requirements [after initial onboarding](https://docs.stripe.com/connect/supported-embedded-components/notification-banner.md#account-onboarding).

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

You can control the collection of `currently_due` or `eventually_due` requirements and the inclusion of [future requirements](https://docs.stripe.com/connect/handle-verification-updates.md) by using the `collectionOptions` attribute when you integrate the notification banner component.

## External account collection

Use the [external_account_collection](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-notification_banner-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-notification_banner-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-notification_banner-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-notification_banner-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 notification banner by specifying `notification_banner` in the `components` parameter.

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

### Render the notification banner component 

#### JavaScript

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

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

#### HTML + JS

| Method                     | Type                                                                                      | Description                                                                                                                                                                                                                            | Default                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `setCollectionOptions`     | `{ fields: 'currently_due' | 'eventually_due', future_requirements: 'omit' | 'include' }` | 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'}` |
| `setOnNotificationsChange` | `({total: number, actionRequired: number}) => void`                                       | Allows users to specify an optional custom behavior in a callback function.

  - `response.total`: The total number of notifications in the banner
  - `response.actionRequired`: The number of notifications that require user action |                                                         |

#### React

| React prop              | Type                                                                                    | Description                                                                                                                                                                                                                                                                       | Default                                                 | Required or Optional |
| ----------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------- |
| `collectionOptions`     | `{fields: 'currently_due' | 'eventually_due', futureRequirements?: 'omit' | 'include'}` | 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             |
| `onNotificationsChange` | `({total: number, actionRequired: number}) => void`                                     | Allows users to specify an optional custom behavior in a callback function.

  - `response.total`: The total number of notifications in the banner
  - `response.actionRequired`: The number of notifications that require user action                                            |                                                         | optional             |

## Configure custom banner behavior

You can configure custom behavior, such as different margins, for when the banner includes any notifications or when the notifications require any action. To do so, set a custom callback function using `onNotificationsChange`.

#### JavaScript

```js
// index.html

<h1 id="notification-banner-action-warning"></h1>

<div id="notification-banner-container"></div>


// index.js
const handleNotificationsChange = (response) => {
  const warning = document.getElementById("notification-banner-action-warning");

  if (response.actionRequired > 0) {
    // Do something related to required actions, such as adding margins to the banner container or tracking the current number of notifications.
    warning.style.display = "block";
    warning.textContent =
      "You must resolve the notifications on this page before proceeding.";
  } else if (response.total > 0) {
    // Do something related to notifications that don't require action.
    warning.style.display = "block";
    warning.textContent = "The items below are in review.";
  } else {
    warning.style.display = "none";
  }
};


const container = document.getElementById('notification-banner-container');
const notificationBanner = stripeConnectInstance.create('notification-banner');
notificationBanner.setOnNotificationsChange(handleNotificationsChange);
container.appendChild(notificationBanner);

```

## Testing

To test this component in a *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes), specify different [test inputs](https://docs.stripe.com/connect/testing.md) for fields that fail verifications or generate requirements on the account. For example, you can use the [account management component](https://docs.stripe.com/connect/supported-embedded-components/account-management.md) to enter `address_no_match` in `line1` of an individual’s address to trigger an address mismatch. In production, it can be difficult to verify that this component is working as expected because it’s hidden when an account has no banner items. To validate your integration is working, you can:

- Set a callback using `onNotificationsChange` that verifies `response.total` is zero
- Confirm the component is being displayed with no content using a [loader start handler](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#reacting-to-component-display)

## Account onboarding

Use the notification banner after the account goes through [account onboarding](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md) and has [details_submitted](https://docs.stripe.com/api/accounts/object.md#account_object-details_submitted). The banner won’t render any UI if the account is missing `details_submitted`.