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.onloadRemember 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();

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

Method	Description
widget.open()	Opens the Widget.
widget.hide()	Closes the Widget without destroying the Widget instance. The Widget is hidden from your customer, and calling `open` again shows it.
widget.destroy()	Removes the Widget instance from your application. To re-open the Widget after calling `destroy`, create another Widget instance with `Fintoc.create()`.

How to use the widget.destroy() methodCalling 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).

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 WidgetCall .open() to open the Widget.

Payment Initiation

Javascript

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

Movements

Javascript

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

Direct Debit

Javascript

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

Parameter	Type	Description
publicKey	string	Identifies your web application or web page within Fintoc. Fintoc assigns `Link` objects created with a `publicKey` to the organization or user that owns the key. The key also determines whether you use the sandbox or production environment: sandbox keys start with `pk_test_`, and production keys start with `pk_live_`.
holderType	string	Type of account to connect to Fintoc. One of `business` or `individual`. Not required for the Payment Initiation product.
product	string	Product and type of `Link` to create. One of `movements`, `subscriptions`, `invoices`, or `payments`.
country	string	Two-letter ISO 3166-1 alpha-2 country code for the country you connect to. One of `cl` (Chile) or `mx` (Mexico). Defaults to `cl`. Not required for the Payment Initiation product.
appearance	object	Controls the Widget color scheme. Includes a `theme` field set to `light` (default) or `dark`. For example: `appearance: { theme: 'dark' }`.
institutionId	string	The `id` of a financial institution. If included, Fintoc pre-selects that institution. For example, `cl_banco_estado` opens the Widget with Banco Estado by default. Before pre-selecting an institution, check availability with the list institutions endpoint.
username	string or object	Pre-fills the username field when making a payment. See the attributes of the `username` object below. If you send a string, it takes the default value for the `editable` attribute.
holderId	string or object	Pre-fills the `holderId` field when connecting a `Link` in the `movements` product. See the attributes of the `holderId` object below. If you send a string, it takes the default value for the `editable` attribute. Only the `movements` product uses this parameter.
sessionToken	string	Token your backend creates when it creates a Checkout Session. The Widget uses `sessionToken` to load and configure the payment flow. Only used for `payments` (Payment Initiation).
webhookUrl	string	URL Fintoc sends a request to after Fintoc creates a `Link`, including the `Link` object’s `link_token`. Only the `movements` and `invoices` products use this parameter; the `payments` and `subscriptions` products do not.
widgetToken	string	Token your backend creates that initializes and configures the Widget. Only the `subscriptions` product uses this parameter.
onSuccess	function	A callback Fintoc calls after the flow finishes successfully.
onExit	function	A callback Fintoc calls after your customer closes the Widget prematurely.
onEvent	function	A callback Fintoc calls each time your customer takes a tracked action in the Widget.

Use the Widget callbacks and events correctlyNever 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 appearanceSend 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 conversionIn Fintoc’s internal testing, pre-filling the username raised payment conversion by 3%.

Attribute	Type	Description
value	string	The `username` or `holderId` to pre-fill on the Widget. For the `payments` product, enter the Chilean tax ID (RUT) in Chile and the phone number in Mexico. For the `movements` product, enter the business RUT of the account you connect.
editable	boolean	Whether the field is editable in the Widget. Defaults to `true`.

Home

Resources

Payments

Transfers

Movements

Web Integration

Plain HTML integration

ES module integration

Methods of the Widget object

How to set up and deploy the Widget

Payment Initiation

Movements

Direct Debit

Username and holderId objects

​Plain HTML integration

​ES module integration

​Methods of the Widget object

​How to set up and deploy the Widget

​Payment Initiation

​Movements

​Direct Debit

​Username and holderId objects

Plain HTML integration

ES module integration

Methods of the Widget object

How to set up and deploy the Widget

Payment Initiation

Movements

Direct Debit

Username and holderId objects