Initializing Components

Embedded banking components can be displayed in any HTML application. Some Javascript or a JavaScript-based framework is necessary for component to work properly.

Read the conceptual article on Authentication before continuing; concepts such as setting a component to use allowAuthentication and silent authentication are uncommon authentication patterns outside of embedded banking.

Note: Encryption keys must be used appropriately for each request and response. For details, see the Event Response and Data Encoding article. This article discusses the component setup rather than sending data request and response.

Allowing Authentication

At least one Embedded Banking component on the page must be marked to allow authentication. The easiest way to do this is to write the allow-authentication attribute in the HTML of the component:

<web-component app-id="{{ appId }}" id="accounts" route="account-balances" allow-authentication></web-component>

This can alternatively be done via Javascript, as described later in this article in Multiple Components on the Same Page.

Note: The HTML attribute includes a hyphen, when the configuration parameter name does not.

Client-Side Event Functions

Three event handler functions are necessary for the embedded banking component to connect to the FI, authenticate the user and disconnect from the FI.

initializeConnect

The initializeConnect event is triggered by the component set to allowAuthentication when the EB Application initiates connecting the Partner User’s Identity to an Financial Institution User’s Identity. The payload of this event allows the partner application to store the association of the Partner User’s Identity with the Financial Institution User’s Identity, and to complete the Auth Flow.

Javascript:

component.addEventListener('initializeConnect', connectHandler);

Angular:

<web-component (initializeConnect)="connectHandler($event)"></web-component>

initializeAuthenticate

The initializeAuthenticate event is triggered by triggered by the component set to allowAuthentication when the EB Application needs to establish a security context for the current user. The payload of this event is used to determine whether the user that is currently logged into the partner app has previously connected to online banking.

Javascript:

component.addEventListener('initializeAuthenticate', authenticateHandler);

Angular:

<web-component (initializeAuthenticate)="authenticateHandler($event)"></web-component>

initializeDisconnect

The initializeDisconnect event can be triggered by any of the Embedded Banking Components on the page and is not limited to the one set to allowAuthentication. The payload of this event is used by the Partner to verify the request is authentic before discarding any stored link between the user’s Financial Institution’s Identity User and the Partner User’s Identity.

Javascript:

component.addEventListener('initializeDisconnect', disconnectHandler);

Angular:

<web-component (initializeDisconnect)="disconnectHandler($event)"></web-component>

Event Payloads

Authentication events contain a payload property containing the authorization parameter to be used by the Partner to complete the flows. Details on processing payloads, including decryption, storing data, and encrypting requests are discussed in the Event Response and Data Encoding article.

{   
"payload": "encoded auth parameter" 
}

Initializing Components

Embedded banking components can be integrated into any HTML-based application that uses Javascript. To integrate components into a page, you need to include the embedded banking script library either on the page or in a corresponding page template:

<script type="module" src="embedded-banking.js"></script>

The library contains wrappers that allow the content to be visible in your application. The actual implementation of the content and data within the components is provided by Apiture servers. The data displayed to the end user inside the component cannot be accessed directly by your application or the page the component resides on. Data that must be passed to the component is passed through parameters where the web component is placed on the page. The parameters include:

The app-id matches the Application ID you received from Apiture when the application was created within the Developer Portal.
The route specifies the Embedded Banking Component to be shown, such as account-balances, transactions or transfers.
The (initialize...) functions register the authentication event handlers in the Partner’s application. On every page, there needs to be one component instance that allows the Partner User’s Identity to connect with their Financial Institution’s User Identity.

One Embedded Banking Component on every page must be built with the following syntax:

<web-component app-id="YourAppId" id="webComponent" route="account-balances" (initializeConnect)="connectionHandler($event)" (initializeAuthenticate)="authHandler($event)" (initializeDisconnect)="disconnectHandler($event)"></web-component>

Multiple Banking Components on the Same Page

To embed multiple components on the same page, some additional configuration is needed. You can apply this configuration using your UI Framework’s HTML Attribute Bindings, or by setting it directly against the HTML Element

				
					// obtain references to the web-component elements

const primaryComponent = document.getElementById('primary-component-id');

const secondaryComponent = document.getElementById('secondary-component-id');

 
// set the configurations

primaryComponent.configuration = { allowAuthentication: true };

secondaryComponent.configuration = { allowAuthentication: false };

The configuration property allowAuthentication indicates which specific component should be used for authentication when there are multiple components.

Only one component may be configured to allowAuthentication set to true when multiple are loaded concurrently. This can also be done with the HTML attribute allow-authentication as described earlier in this document.

The other components are not required to explicitly have allowAuthentication set to false. The configuration parameter may be excluded. However, the component will be treated like it is set to false.

Warning: Setting more than one component to allowAuthentication will cause breaking race conditions.

For the single Embedded Banking Component configured to allowAuthentication, the initializeConnect, initializeAuthenticate, initializeDisconnect properties and corresponding handlers are required, as documented in the section above.

All components require the initializeDisconnect property and handler. The initializeConnect and initializeAuthenticate are not required when allowAuthentication is false.

Any additional Embedded Banking Components that do not allowAuthentication can use the following syntax:

<web-component app-id="YourAppId" id="webComponent" route="account-balances" (initializeDisconnect)="disconnectHandler($event)"></web-component>