Web Integration

This page shows how to embed the Fintoc Widget in a web application or web page. It covers the plain HTML script tag, ES module setup, Widget object, configuration parameters, and callbacks.

Plain HTML integration

To integrate the Widget, include the Fintoc script in your HTML page. Include the script on each page where you use the Widget.

<script src="https://js.fintoc.com/v1/"></script>

📘

window.onload

Remember that, when importing a JavaScript script, if you try to use functions before the browser loads the script, an error will be raised. You can solve this by using the native browser event window.onload.

ES module integration

You can also use the Widget as an ES module through npm with the @fintoc/fintoc-js library.

npm install @fintoc/fintoc-js

The library exports an async getFintoc method that returns the Fintoc object.

import { getFintoc } from '@fintoc/fintoc-js';

// See the parameter table below for the full list of options
const options = {
  product: 'payments',
  publicKey: 'YOUR_PUBLIC_KEY',
  sessionToken: 'YOUR_SESSION_TOKEN',
};

const main = async () => {
  const Fintoc = await getFintoc();
  const widget = Fintoc.create(options);
  widget.open();
}

main();

Methods of the Widget object

Once you create a Widget object, you can use its methods to interact with it. The available methods are open, hide, and destroy.

📘

How to use the widget.destroy() method

Calling Fintoc.create(args) embeds an iframe in your application. When you develop a single-page application (SPA), you may need to remove this iframe. The destroy method removes it. To re-open the Widget afterward, create a new instance with Fintoc.create(args).

How to set up and deploy the Widget

Each product sets up and deploys the Widget on your front end differently.

Including the Fintoc script in your application (or calling the getFintoc method of the @fintoc/fintoc-js library) exposes the Fintoc class. The Fintoc class creates connections to a financial institution from your application.

📘

Raise the Widget

Call .open() to open the Widget.

Payment Initiation

const widget = Fintoc.create({
  product,
  publicKey,
  sessionToken,
  onSuccess,
  onExit,
  onEvent,
})

Movements

const widget = Fintoc.create({
  holderType,
  product,
  publicKey,
  webhookUrl,
  country,
  institutionId,
  linkToken,
  onSuccess,
  onExit,
  onEvent,
})

Direct Debit

const widget = Fintoc.create({
  holderType,
  product,
  publicKey,
  country,
  institutionId,
  widgetToken,
  onSuccess,
  onExit,
  onEvent,
})

❗️

Use the Widget callbacks and events correctly

Never use the onSuccess, onExit, or onEvent callbacks to read the state of the resource being created. Use these callbacks only to drive your frontend flow while you wait for backend confirmation, either through webhooks or by exchanging a confirmation token. You can also use frontend events to generate Widget usage metrics. Never rely on frontend events alone to assume a resource was created or failed to be created.

📘

Dark mode for the Widget appearance

Send the appearance parameter to set the Widget color scheme to light or dark mode.

Username and holderId objects

To pre-fill username or holderId and override the defaults, send an object with these attributes:

const username = {
  value: '11.111.111-1',
  editable: true,
};

const holderId = {
  value: '11.111.111-1',
  editable: true,
};

📘

Pre-filling raises payment conversion

In Fintoc's internal testing, pre-filling the username raised payment conversion by 3%.