Log In / Register

Initializing Components

Embedded banking components can be displayed in any HTML page. 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.

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 the process of 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 the Primary Auth Component 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 Component 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 page. 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 of 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 during the Partner App Registration process.

  • The route specifies the Embedded Banking Component to be shown, such as account-balances, transactions or transfers.

  • The (initialize...) properties 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 when multiple are loaded concurrently.

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>
On this page