Embedded Web Form 2.0
Prerequisites
CORS configuration
Since the embedded Web Form works as a part of your web page, but still has to communicate with *.finapi.io domains, all modern web browsers will apply Cross-Origin Resource Sharing (CORS) policies to all requests triggered by the Web Form scripts. finAPI Web Form 2.0 backend takes care of it and makes sure to only process requests from domains you allow. By default, no domains are allowed for customers, and they must be explicitly configured.
If you try to use the embedded Web Form, but it apparently fails, and you see “CORS error” in the Network tab of DevTools in the browser, it means CORS configuration is missing for your mandator.
To eliminate this issue, you need to provide us with all domains where you are going to use the embedded Web Form. For that, please raise a request to our support team, and they will take care of the rest.
Please note that due to security requirements, it is not allowed to use any local domains (e.g. localhost or 127.0.0.1) in the CORS configuration. If you want to test your application running on a local machine, consider using public services that can route your local traffic to a domain available on the Internet.
Web Form Loader
Web Form is bundled as a Web Component.
Web Components is a suite of different technologies allowing you to create reusable custom elements — with their functionality encapsulated away from the rest of your code — and utilize them in your web apps. (source)
This means you can attach a Web Form as a custom DOM element to your web page. Web Form is rendered under Shadow root which prevents conflicts with your host application (e.g. CSS styling issues). To make things even easier, we provide you with a Web Form Loader.
Web Form Loader is a small JavaScript library that takes care of loading and unloading Web Form to and from your page.
Type definitions as well as all options supported by the Web Form Loader can always be found here: https://webform-dist.finapi.io/latest/docs/modules.html
Usage
Usage via script
To use Web Form in simple HTML code, one could do it like this:
<div id="webFormContainer"></div>
<script src="https://webform-dist.finapi.io/latest/dist/web-form.min.js"></script>
<script>
const createWebForm = async function () {
// Replace the following line with a real HTTP request to one of the services that create a web form
// ("Import a bank connection", "Update a bank connection", and others).
// Use the `id` field's value of the created web form as the value for the `token` then.
const token = await Promise.resolve("<token>");
FinApiWebForm.load(
document.querySelector("#webFormContainer"),
{
token: token,
// these are examples of how optional properties can be set:
targetUrl: "https://webform-live.finapi.io",
layoutConfig: "xs",
backToAppUrl: "https://customer.app",
customerSupportUrl: "https://finapi.io",
language: "de"
},
{
onLoaded: function() {
// handle "onLoaded" event
},
onComplete: function() {
// handle "onComplete" event
},
onFail: function() {
// handle "onFail" event
},
onAbort: function() {
// handle "onAbort" event
},
onLoadError: function() {
// handle "onLoadError" event
}
}
);
};
document.addEventListener("DOMContentLoaded", function() {
createWebForm();
});
</script>Before you can load a web form, you will need to first obtain a valid token - more info in Web Form Basics. For each next load, a new token should be provided.
web-form.min.js contains an IIFE - immediately invoked function expression, which will create a globally-scoped variable FinApiWebForm. This variable name is therefore reserved.
It is possible to "freeze" the version by replacing the latest tag with the desired version: https://webform-dist.finapi.io/2.6.0/dist/web-form.min.js
A list of all the available versions can be found in the NPM version history.
Usage as a module
Web Form Loader can also be installed as an NPM package:
npm install @finapi/web-formThis package exports functions load() and unload(). It also provides TypeScript type declarations.
An example of usage in React framework could look like this:
import React, { useCallback } from "react";
import { load } from "@finapi/web-form";
function App() {
return <FinApiWebForm />;
}
function FinApiWebForm() {
const createWebForm = useCallback(async (target: HTMLElement) => {
// Replace the following line with a real HTTP request to one of the services that create a web form
// ("Import a bank connection", "Update a bank connection", and others).
// Use the `id` field's value of the created web form as the value for the `token` then.
const token = await Promise.resolve("<token>");
load(
target,
{
token: token,
// these are examples of how optional properties can be set:
targetUrl: "https://webform-live.finapi.io",
layoutConfig: "xs",
backToAppUrl: "https://customer.app",
customerSupportUrl: "https://finapi.io",
language: "de"
},
{
onLoaded: function() {
// handle "onLoaded" event
},
onComplete: function() {
// handle "onComplete" event
},
onFail: function() {
// handle "onFail" event
},
onAbort: function() {
// handle "onAbort" event
},
onLoadError: function() {
// handle "onLoadError" event
}
}
);
}, []);
const containerRef = (container: HTMLDivElement) => {
if (container) {
createWebForm(container);
}
};
return <div ref={containerRef}></div>;
}
export default App;Web Form Loader module requires minimum ES5 support.
Versions and tags
A list of all the available versions can be found in the NPM version history.
latest- stable release version that is tested and synced with the live production environment.alpha- an unstable pre-release version that might be out of sync with the live production environment.
Configuring the Web Form Loader
Docs
Web Form Loader typedoc can be found here: https://webform-dist.finapi.io/latest/docs/modules.html.
Working with custom environments
The loader works by default with the Live environment (https://webform-live.finapi.io), but it might happen that you have a custom environment working on another subdomain, e.g. https://custom-webform.finapi.io. In such cases, please use the targetUrl parameter provided by the loader in order to overwrite the default behavior. You can always clarify with our Customer Support team if it applies to your setup.
Adjusting the layout of the web form
By default, the embedded web form will choose its layout config based on the current viewport size. Due to technical limitations, only the size of the “main” viewport is taken into consideration and the size of the actual web form component is ignored. That sometimes might lead to an undesired “look and feel” of the web page. In such cases, the default layout config can be overridden via the Loader property layoutConfig, where you can either use one of the predefined values (xs, sm, md, and lg) or provide your custom breakpoints. For the type definition of the property, check the typedoc.
Frontend callbacks
When embedding a web form in either way described above, callback functions can be passed directly to the web form loader during the initialization phase. These functions, if provided, will be triggered when the corresponding event occurs, e.g., when the web form is completed. In that way, you can either avoid using our “server” callbacks (listed in this section) or combine both approaches in order to provide the best user experience.
Find the full list of supported callbacks, as well as more details about how they function in the typedoc.
Demo
We have prepared mini-DEMO(s) on how standalone and embeddable Web Forms could look. Please feel free to take a look.
00:00 General Introduction
01:45 Explanation of how standalone Web Form works
05:14 Demo
12:05 Explanation on how to embed the Web Form into a customer web page
15:00 Demo
19:42 Explanation on how to integrate the Web Form into an Android app
21:51 Demo