regprotect-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/regprotect-web-component/dist/ba-regprotect.js"></script>

Properties

| Property | Attribute | Type | Description | |---------------|----------------|-----------|------------------------------------------------------------------------------------------------------------------------------------| | sessionLink | session-link | string | This link provides session information and the customer callback URL, which you are redirected to as soon as REG/Protect process is finished | | reentryUrl | reentry-url | string | REG/Protect Web Component needs to be reinstantiated when you get redirected to this URL. Background: A user of a provider/bank sometimes needs to perform a Redirect SCA (Strong Customer Authentication) to authenticate with the bank/provider on the banks/providers website |

Events

| Event | Type | Description |
|--------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | subscribed | CustomEvent | Event emitted when REG/Protect process is finshed. "event.detail" contains the link where you can take the user back (this is the same link which was part of "sessionLink" as the "callbackUrl" query param) |

ba-regprotect

First, in the HTML, we need to define a container element where our web component will be mounted. This container can be any element, including the document body.

<div id="ba-reprotect-container"></div>

Some JavaScript is required to create the web component and handle its events.
The first step is to generate a BANKS/Connect token.
Important: This step should be performed on the backend to avoid exposing your BANKS/Connect API credentials in the frontend.
Once you have the token, use it to invalidate all previous REG/Protect sessions for the corresponding user.

async function invalidateSessions() {
  try {
    const response = await fetch(`https://banksapi.io/customer/regshield/sessions`, {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
    });

    if (!response.ok) {
      throw new Error(`${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    console.log('invalidate sessions done:', data);
  } catch (error) {
    console.error('invalidate sessions endpoint error:', error);
  }
}

This will give us a fresh start, so we can now implement a use case like adding a bank access

async function addBankAccess() {
  try {
    // you decide what ID (usually UUIDv4) you bank access will have
    const accessId = generateUUID();
    const payload = {
      [accessId]: {}
    }
    const response = await fetch(`${API_DOMAIN}/customer/v2/bankzugaenge`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Customer-Ip-Address': customerIp,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload),
    });

    const location = response.headers.get('Location');
    // the Callback URL, will only be used in the "subscribed" event, but must adhere to the whitelist that you communicated to BANKSapi
    const callbackUrl = `${window.location.href}?event=accessCreated&accountId=${accessId}`;
    if (!location || callbackUrl.length === 0) {
      alert('the bank access request was not successful, please check your network log');
    } else {
      const wcConfirm = confirm('Switching to REG/Protect. OK?');
      if (wcConfirm) {
        const sessionLink = `${location}&callbackUrl=${callbackUrl}`;
        console.log('[sessionLink]', sessionLink);
        console.log('creating web component');
        this.createWCElement(sessionLink);
      }
    }
  } catch (error) {
    console.error('adding the bank access resulted in an error:', error);
  }
}

function createWCElement(sessionLink) {
  const demoButton = document.getElementById('start-demo');
  wcContainer = document.getElementById('ba-reprotect-container'); //.attachShadow({mode: 'closed'});
  wcElement = document.createElement('ba-regprotect');
  wcElement.sessionLink = sessionLink;
  // URL where the user will be redirected after performing SCA at Bank Provider
  wcElement.reentryUrl = 'some.example.url/path';

  wcContainer?.classList.add('regprotect-active')
  wcContainer?.appendChild(wcElement);

  wcElement.addEventListener('subscribed', handleWebComponentListener);
}

function handleWebComponentListener(event) {
  const demoButton = document.getElementById('start-demo');
  console.log('[REG/Protect WC event]', event);
  console.log('[REG/Protect WC event]', event.detail);
  // event.detail will look something like this ->
  // http://localhost:8081/?event=accountCreated&accountId=06f589bd-8d35-494a-8056-2e5d927a3aa3&baReentry=ACCOUNT_CREATED

  const callbackUrl = event.detail;
  // evaluate query param, handle event and/or baReentry

  // add use cases for add bank access, payments, etc., remove web component from DOM beforehand
  wcContainer?.removeChild(wcElement);
  wcContainer?.classList.remove('regprotect-active');

  console.log('web component event listener removed.');
  wcElement.removeEventListener('subscribed');
  wcElement = undefined;
}