Notification banner

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.

Requirements collection options

You can control the collection of currently_due or eventually_due requirements and the inclusion of future requirements by using the collectionOptions attribute when you integrate the notification banner component.

External account collection

Use the external_account_collection feature to control whether the component collects external account information. This parameter is enabled by default, and only platforms responsible for collecting updated information when requirements are due or change (including Custom accounts) can disable it. When external_account_collection is enabled, user authentication is required. You can opt out of Stripe user authentication with the disable_stripe_user_authentication parameter.

Disable Stripe user authentication

Use the disable_stripe_user_authentication feature to control whether the component requires Stripe user authentication. The default value is the opposite of the external_account_collection value. For example, if you don’t set external_account_collection, it defaults to true and disable_stripe_user_authentication defaults 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. 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.

Create an Account Session

When creating an Account Session, enable notification banner by specifying notification_banner in the components parameter.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[notification_banner][enabled]"=true \
  -d "components[notification_banner][features][external_account_collection]"=true

Render the notification banner component

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

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

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.

// 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, specify different test inputs for fields that fail verifications or generate requirements on the account. For example, you can use the account management component 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

Account onboarding

Use the notification banner after the account goes through account onboarding and has details_submitted. The banner won’t render any UI if the account is missing details_submitted.