Integrate the widget

🚧

Warning

This guide is meant to be followed by a frontend. If your application needs to integrate the widget, you need a frontend for the widget to live in. You will also need a backend to store the created Links.

Before we can start using the widget, you need to get your Fintoc account's Public Key. It will be used throughout this guide, so make sure to follow the guide on how to get your API keys to get your live Public Key.

📘

Tip

You should integrate the widget when you want the users of your application to create their own Links dynamically. For example, if your application is meant for users to see aggregated data about their bank accounts, you probably need to integrate the widget, as you will need each client to create a Link with their bank data. On the other hand, if you want to try out Fintoc, you can try and interact only with the data of your own bank account, by creating a Link through the dashboard and directly using it.

You can think of the widget as useful when you want to connect with your users' bank accounts, and unnecessary when you're trying out Fintoc, thus only ever using one static Link that you can hardcode.

To integrate the widget, you first need to load the widget script.

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

// Use the Load Script plugin
// https://github.com/tserkov/vue-plugin-load-script
async function loadFintoc() {
  await Vue.loadScript('https://js.fintoc.com/v1/');
  return window.Fintoc;
}

const Fintoc = await loadFintoc();

// Use the React Script hook
// https://github.com/hupe1980/react-script-hook
function useFintoc() {
  const [loading, error] = useScript({ src: 'https://js.fintoc.com/v1/' })
  return [window.Fintoc || null, loading, error];
}

const [Fintoc, loading, error] = useFintoc();

Now, you can use the Fintoc class to instantiate the widget!

📘

Tip

Because we will need to use our Public Key, some information needs to be replaced by you to make the code from this guide fully functional. From now on, we will write FINTOC_PUBLIC_KEY to represent the Public Key that you need to replace.

<script>
  window.onload = () => {
    const widget = Fintoc.create({
      publicKey: 'FINTOC_PUBLIC_KEY',
      holderType: 'individual',
      product: 'movements',
      webhookUrl: 'https://my-url.com/receive/webhook',
      onSuccess: (link) => {
        console.log('Success!');
        console.log(link);
      },
      onExit: () => {
        console.log('Widget closing!');
      },
      onEvent: (event) => {
        console.log('An event just happened!');
        console.log(event);
      },
    });
  };
</script>

const Fintoc = await loadFintoc();

const widget = Fintoc.create({
  publicKey: 'FINTOC_PUBLIC_KEY',
  holderType: 'individual',
  product: 'movements',
  webhookUrl: 'https://my-url.com/receive/webhook',
  onSuccess: (link) => {
    console.log('Success!');
    console.log(link);
  },
  onExit: () => {
    console.log('Widget closing!');
  },
  onEvent: (event) => {
    console.log('An event just happened!');
    console.log(event);
  },
});

const [Fintoc, loading, error] = useFintoc();

const widget = Fintoc.create({
  publicKey: 'FINTOC_PUBLIC_KEY',
  holderType: 'individual',
  product: 'movements',
  webhookUrl: 'https://my-url.com/receive/webhook',
  onSuccess: (link) => {
    console.log('Success!');
    console.log(link);
  },
  onExit: () => {
    console.log('Widget closing!');
  },
  onEvent: (event) => {
    console.log('An event just happened!');
    console.log(event);
  },
});

Notice that the widget needs to receive the following configuration parameters:

• publicKey: Your Fintoc Public Key, you can retrieve it following this guide.
• holderType: The type of account of the finantial entity to connect.
• product: The product that the created link will have access to.
• webhookUrl: The URL to send the complete Link information to (the Link passed to the onSuccess method is incomplete, as it does not include the Link Token, but the Link sent to the webhookUrl does include the Link Token). Note that this URL should be a URL of your backend.
• onSuccess: A function that executes upon completition of the frontend workflow for the creation of a Link.
• onExit: A function that executes when the widget gets closed (for any reason other than a page reload).
• onEvent: A function that executes when the widget triggers an event.

You can read more about these configuration parameters and their possible values on the official documentation.

We already loaded the script and instantiated the widget. Now, all that's left is to open it!

<script>
  widget.open();
</script>

widget.open();

widget.open();

At this point, you should see the widget on your screen when loading the page:

Whenever a user finishes the workflow for creating a Link, two things will happen:

1. Fintoc will send a webhook to the webhookUrl you specified when instantiating the Fintoc object. This webhook will contain all the information of the new Link. You should save this information to your database, as the Link Token will only be sent here, and you need to use that datum to query the Fintoc API.
2. The widget will execute the onSuccess function, and will pass the new Link as a parameter. Notice that the Link passed to the onSuccess function does not contain the Link Token. You should probably store this new information on the browser memory, as the workflow for using the new Link involves sending the Link id to the backend, using that id to get the Link Token and using that token to query the Fintoc API, finally returning the data to the frontent.

A (very simplified) version of the complete workflow would look something like this: