TaleFin Home
Login

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:

NameDetails
VENDOR_LABELLabel that uniquely identifies your vendor account.
Provided to you by TaleFin when your account is provisioned.
VENDOR_SPECIFIC_IDID that uniquely identifies the active client.
This is used primarily for correlating data you receive from TaleFin against your own system's records, generally the UUID for this client in your own system would be used.

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" />
NameFlag
Multiplemultiple=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.

NameFlag
Account Selectioncollect=select_accounts
Balancescollect=balances
Transactionscollect=transactions
Interimscollect=interims
Estatementscollect=estatements
Analysiscollect=analysis
Account Ownercollect=account_owner

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.

FlagDescription
success_urlThe destination to send the user to after a COMPLETED crawl.
failure_urlThe destination to send the user to after a FAILED or DIED crawl.

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 #

NameDefault ValueDescription
colorPrimary#FFB000Primary branding colour - used as highlights for icons, buttons and links.
colorSecondary#F9F9F9Secondary branding colour - used as the background of the shaded top bar.
colorBackground#FFFFFFBackground colour - used as the general background across all pages.
fontDM+SansBranding font - any font available on Google Fonts can be specified by name and will be dynamically downloaded and used.

Prefilling Details

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

NameDescription
firstNameClient's first name
lastNameClient's last name (including any middle names)
phoneNumberClient's phone number
emailClient's email address

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:

PathOutcome
/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}Standard application flow, beginning with asking for client's details.
/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}/banksSkip client details & informational prelude steps, going directly to the bank selection step.
REQUIRED: Customer Details must be provided via query string paramaters.
/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}?bank={bank_id}Skip client details and prelude steps, and prefill the iFrame with the designated bank. (Bank ID currently differs on production and staging environments)

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};

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};

Start Now

Subscribe to our newsletters

Subscribe to our newsletter and stay up to date with the latest news about TaleFin.

FDATA
TaleFin Home© Copyright 2024 TaleFin Australia Pty Ltd. ABN 71 632 551 770