bam-web-component

This library is maintained by BANKSapi Technology GmbH. For an overview of the features and benefits, visit our Banking Widgets page.

You can find more helpful technical documentation for this and other products in our developer portal. For support or assistance with integration, feel free to contact us.

Usage

We recommend including this library via a public CDN to automatically benefit from future improvements without requiring any action on your part.

<script src="https://cdn.jsdelivr.net/npm/@banksapitechnology/bam-web-component/dist/bam.min.js"></script>

The web component is authenticated by a BANKS/Connect token. Provide the token either through the token prop or by storing it in the LocalStorage under the key ba-token.

ba-bam-dashboard

Properties

| Property | Type | Allowed values | Default | Description | | -------------------- | ------------- | -------------------------------- | ---------- | -------------------------------------------------------------------------- | | token | string | — | (required) | BANKS/Connect authentication token | | enableUserDeletion | boolean | true, false | false | Allows user deletion via a delete button at bottom of the web component | | maxTransactions | string (enum) | none, all, paymentAccounts | none | Controls transaction data fetching behavior | | proceedElement | boolean | true, false | false | Enables a custom element slot for host app to inject custom UI elements |

Events

| Event | Type | Detail | | -------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | openRegprotect | CustomEvent<{ sessionLink: string }> | Emitted when an SCA or REG/Protect flow is triggered. The host app should listen for this event and redirect using the provided session link. | | openBankingView | CustomEvent | Emitted when the "Zum Kundenportal" button is clicked. Its used for page navigation. | | tokenInvalid | CustomEvent<{ status: 403 }> | Emitted when the token is explicitly rejected by the introspection endpoint or when token is not provided as props to the web component. Here, 403 and 401 represent invalid and unauthenticated token respectively | | loadDashboardError | CustomEvent<{ error?: any }> | Emitted when the dashboard fails to load due to a network error or when BAM service is down. | | bamRefresh | CustomEvent | Received by the component to trigger a refresh of the bank accesses list. Dispatch this event to reload the dashboard content. | | deleteUser | CustomEvent | Emitted when delete user is triggered. Host app should either reload dashboard or destroy the web component. | | bankAccessListEmpty| CustomEvent<{ empty: boolean }> | Indicates whether the rendered bank access list is empty (true) or contains at least one access (false); emitted after every dashboard refresh and HTMX swap. |

Example payload

{
    sessionLink: "https://banksapi.io/some-session-link&callbackUrl=...",
    reason: "accessCreated" // optional
}

Custom Element Slot

When proceedElement is set to true, the dashboard renders a <slot name="custom-element"> that allows the host app to inject custom UI elements (e.g., buttons, forms) at a designated position in the dashboard.

Usage:

<ba-bam-dashboard token="your_token" proceed-element="true">
  <button slot="custom-element" class="btn btn-primary" onclick="handleProceed()">
    Continue to Next Step
  </button>
</ba-bam-dashboard>

<script>
  function handleProceed() {
    console.log('Custom button clicked!');
    // Your custom logic here
  }
</script>

The slotted content:

• Appears below the list of bank accesses (when at least one bank access exists)
• Has no access to backend data (isolated in shadow DOM)
• Can be styled and programmed entirely by the host app
• Supports any HTML element and custom event handlers

REG/Protect integration

When using <ba-bam-dasboard> web component, you can hook into REG/Protect web component use cases like:

• Add Bank Access
• Providing Strong Customer Authentication (SCA)
• Change Bank Products

This is accomplished through the REG/Protect web component An example implementation is shown below

<div id="wc-container">
  <ba-bam-dasboard token="your_banksconnect_token_here"></ba-bam-dasboard>
</div>

<script src="https://cdn.jsdelivr.net/npm/@banksapitechnology/bam-web-component/dist/bam.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@banksapitechnology/regprotect-web-component/dist/ba-regprotect.js"></script>
<script>
  const container = document.getElementById("wc-container");

  container.addEventListener("regprotect-redirect", (event) => {
    const { sessionLink, reason } = event.detail;
    console.log("[Host] RegProtect triggered:", sessionLink, reason);

    // Optional: Clean up or hide existing component
    container.innerHTML = ""; // or animate out <ba-bam-dasboard> manually

    // Add <ba-regprotect> dynamically
    const regprotect = document.createElement("ba-regprotect");
    regprotect.setAttribute("sessionLink", sessionLink);
    container.appendChild(regprotect);

    // (Optional) Handle further REG/Protect completion events
    regprotect.addEventListener("subscribed", () => {
      console.log("[Host] REG/Protect finished. Restoring dashboard...");

      const bam = document.createElement("ba-bam-dasboard");
      bam.setAttribute("token", localStorage.getItem("ba-token"));
      container.replaceChildren(bam);
    });
  });

  // Example: Refresh the bank accesses list
  const bamComponent = document.querySelector("ba-bam-dasboard");
  bamComponent.dispatchEvent(new CustomEvent("bamRefresh"));
</script>