iFrame Guide
Login

Iframe Guide

Overview

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

One-line example HTML:

1<iframe src="https://credfin.io/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 Credfin when your account is provisioned.
VENDOR_SPECIFIC_IDID that uniquely identifies the active client.
This is used primarily for correlating data you receive from Credfin against your own system's records, generally the UUID for this client in your own system would be used.

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://credfin.io/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://credfin.io/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}?collect=account_owner&collect=analysis" />

The account selection feature is currently 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

Branding

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
colorPrimaryFFB000Primary branding colour - used as highlights for icons, buttons and links.
colorSecondaryF9F9F9Secondary branding colour - used as the background of the shaded top bar.
colorBackgroundFFFFFFBackground colour - used as the general background across all pages.
fontJosefin+SansBranding font - any font available on Google Fonts can be specified by name and will be dynamically downloaded and used.

For example; if your brand uses orange as primary and white as secondary brand colours, with dark grey backgrounds and the "Open Sans" font, you might use something like this:

1<iframe src="https://credfin.io/i/{VENDOR_LABEL}/{VENDOR_SPECIFIC_ID}?colorPrimary=FFAA00&colorSecondary=FFFFFF&colorBackground=333333&font=Open+Sans" />

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://credfin.io/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:

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_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 Credfin 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 accoridngly 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};
Subscribe to our newsletters

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

FDATA