Account Owner Guide

Overview

Using TaleFin's iframe endpoint you can quickly and easily integrate the Account Owner check into your existing workflow. Not all payload fields (see payload below) can be retrieved from all institutions. Other common causes of failure to retrieve are scenarios such as when the customer has not registered for eStatements, their account profile hasn't been completed (new account) or the institution is simply not providing any data. In cases where no data can be retrieved, a failure message will be provided along with the payload.

One-line example in HTML:

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:

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.

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

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

This service 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:

Name	Details
`VENDOR_LABEL`	Label that uniquely identifies your vendor account. Provided to you by TaleFin when your account is provisioned.
`VENDOR_SPECIFIC_ID`	ID 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.
`?collect=account_owner`	The flag to instruct the iFrame to only collect the account owner information. Additional flags can be supplied if additional features are required.

Customising Collection Services

The full list of options is available below. For even more options refer to the iFrame Guide; however for Account Owner only the account_owner owner options is required.

Name	Flag
Balances	`collect=balances`
Transactions	`collect=transactions`
Interims	`collect=interims`
Estatements	`collect=estatements`
Analysis	`collect=analysis`
Account Owner	`collect=account_owner`

Prefilling Details

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

Name	Description
`firstName`	Client's first name
`lastName`	Client's last name (including any middle names)
`phoneNumber`	Client's phone number
`email`	Client's email address

For example:

1<iframe src="https://banks.talefin.com/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}?firstName=Mickey&lastName=Mouse&email=mickey@disney.com&phone=04123128321" />

Deep Linking

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

Path	Outcome
`/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}`	Standard application flow, beginning with asking for client's details.
`/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}/banks`	Skip 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_ID}`	Skip customer details & informational prelude steps plus the bank selection step, directly pre-selecting the specified bank and prompting the customer to log in. REQUIRED: Customer Details must be provided via query string paramaters.

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