Iframe Guide

Overview

Using TaleFin's iframe endpoint you can quickly and easily integrate your existing systems with TaleFin's solutions.

One-line example HTML:

1<iframe src="https://banks.talefin.com/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}" />

As the title of this guide suggests this endpoint is intended to be used through an iframe embedded in your page, however the URL can also be sent as a link directly to clients via e-mail, SMS or any text-based messaging system you already integrate with.

Required Parameters

The following URL paramaters are required, if they are missing or incorrect the client will receive a "Page Not Found" error:

Requesting Multiple Institutions

By default, we only collect one institution per application. This behaviour can be overridden by specifying multiple query parameter to be true.

For example, in order to request multiple institutions for the client, you may use something like this:

1<iframe src="https://banks.talefin.com/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}?multiple=true" />

Customising Collection Services

By default, only the analysis option is enabled when creating a profile. This behaviour can be overridden by specifying collection query parameters. When including a collection query parameter in your iframe URL, only the specified services will be enabled.

For example, in order to only request account owner information for the client, you may use something like this:

1<iframe src="https://banks.talefin.com/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}?collect=account_owner" />

In order to request multiple services, simply specify the collect flag again. For example, in order to request an analysis in addition to account owner information, you may use something like:

1<iframe src="https://banks.talefin.com/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}?collect=account_owner&collect=analysis" />

The account selection feature is only available on the v2 iFrame. This will provide the user with a set of checkboxes to select which accounts should be crawled before submitting the application.

The full list of options is available below.

Automatic Redirecting

The automatic redirection feature is only available on the v2 iFrame. This will send the user to the designated URL depending on the outcome of the application.

Branding

This feature has been migrated from query string parameters to vendor endpoint fields. Provide your desired values and our developers will configure your vendor profile to match.

The user interface can be configured to match your branding by specifying the query string parameters shown in the table below.

Colours must be specified in hex format, without the leading hash/pound sign #

Prefilling Details

The client's personal details can be pre-filled with data from your own system via the following query string parameters:

For example:

1<iframe src="https://banks.talefin.com/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}?firstName=John&lastName=Citizen&email=test@banks.talefin.com&phoneNumber=0400000000" />

Deep Linking

Parts of the process can be skipped by deep-linking with any required information provided via query string parameters:

Events

The iframe emits postMessage events in response to certain actions, you can listen to these events in order to enable your own website or system to react to changes in the ongoing TaleFin application.

Each event will contain an event.data.type field which specifies the type of event being fired, from this you can determine your desired behaviour for that given event.

NOTE

DO NOT rely on these events or any client-side behaviour for important business logic as their execution in the browser can never be guaranteed. Only webhooks should be used for mission-critical processes.

Resizing

An event of type resize is fired when the content changes size, you can listen to this and resize the iframe's external dimensions accordingly so the iframe automatically expands to present all content, avoiding nested scrolling:

1window.addEventListener('message', function (event) {
2  if (event.data.type === 'resize') {
3    document.querySelector(
4      'iframe#credfin',
5    ).style = `height: ${event.data.height}px`;
6  }
7});

In this case event.data contains the following fields:

1type Resize = {
2  height: number;
3  width: number;
4};

Navigation

An event of type loaded is fired when the client progresses to another step which completes loading, generally in response to this you would scroll them to the top of the page since navigating inside the iframe does not reset their scroll to the top as a full page load usually does.

1window.addEventListener('message', function (event) {
2  if (event.data.type === 'loaded') {
3    window.scrollTo({top: 0, behavior: 'smooth'});
4  }
5});

In this case event.data contains a single property page which may be any value in the following enum type:

1enum Pages {
2  loading = 'loading',
3  userDetails = 'userDetails',
4  prelude = 'prelude',
5  banks = 'banks',
6  crawler = 'crawler',
7}

Client Details

An event of type clientDetails is fired when the client completes submission of their personal details, this information can also be retrieved via the Profile API, however to avoid unnecessary network requests you can simply listen to this event.

Typically you would use these client details to personalize the presentation of your application form or pre-fill/skip asking the client for this data again in your own subsequent account registration form.

1window.addEventListener('message', function (event) {
2  if (event.data.type === 'clientDetails') {
3    document.querySelector('input.email').value = event.data.email;
4  }
5});

In this case event.data contains the following fields:

1type ClientDetails = {
2  firstName: string;
3  lastName: string;
4  phoneNumber: string;
5  email: string;
6  title: string;
7};