Integrate the Widget on the web

Embed the Fintoc Widget in a web application with an HTML script tag or an ES module. This page also covers Widget methods, 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.

Client

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

window.onloadThe browser raises an error if you call a Fintoc function before the script loads. Use the native window.onload event to wait for the script.

ES module integration

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

Client

npm install @fintoc/fintoc-js

The library exports the asynchronous getFintoc function. This function returns the Fintoc object.

Client

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

After you create a Widget instance, use its open, hide, and destroy methods to control the instance:

Method	Description
`widget.open()`	Opens the Widget.
`widget.hide()`	Closes the Widget without destroying the Widget instance. The Widget remains hidden until you call `widget.open()` again.
`widget.destroy()`	Removes the Widget instance from your application. To reopen the Widget, create another Widget instance with `Fintoc.create()`.

How to use the widget.destroy() methodCalling Fintoc.create(args) embeds an iframe in your application. In a single-page application, you may need to remove the iframe. Call widget.destroy() to remove the iframe. To reopen the Widget, create a new instance with Fintoc.create(args).

Each product requires different Widget configuration parameters. Loading the Fintoc script gives your application access to the Fintoc object. The getFintoc function from @fintoc/fintoc-js returns the same object. Use Fintoc.create() to create a Widget instance for your product.

Open the WidgetCall widget.open() to open the Widget.

Payment initiation

Client

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

Movements

Client

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

Direct debit

Client

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

Configure the Widget with these parameters:

Parameter	Type	Description
`publicKey`	`string`	Identifier for your web application or web page within Fintoc. Fintoc assigns each `Link` created with the key to the key’s owner. 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 Payment Initiation.
`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. One of `cl` (Chile) or `mx` (Mexico). Defaults to `cl`. Not required for Payment Initiation.
`appearance`	`object`	Widget color scheme. Contains a `theme` field set to `light` or `dark`. Defaults to `light`. For example, `appearance: { theme: 'dark' }`.
`institutionId`	`string`	Identifier of a financial institution. If included, Fintoc preselects that institution. For example, `cl_banco_estado` opens the Widget with Banco Estado selected. Confirm availability with the list institutions endpoint before preselecting an institution.
`username`	`string` or `object`	Value that pre-fills the `username` field when making a payment. See the `username` object attributes. A string sets `editable` to its default value of `true`.
`holderId`	`string` or `object`	Value that pre-fills `holderId` when connecting a `Link` for `movements`. See the `holderId` object attributes. A string sets `editable` to its default value of `true`. Only `movements` uses this parameter.
`sessionToken`	`string`	Token your backend creates with a Checkout Session. The Widget uses `sessionToken` to load and configure the payment flow. Only `payments` uses this parameter.
`webhookUrl`	`string`	URL that receives a request after Fintoc creates a `Link`. The request includes the `Link` object’s `link_token`. Only `movements` and `invoices` use this parameter.
`widgetToken`	`string`	Token your backend creates to initialize and configure the Widget. Only `subscriptions` uses this parameter.
`onSuccess`	`function`	Callback Fintoc calls after the flow finishes successfully.
`onExit`	`function`	Callback Fintoc calls after your customer closes the Widget before completing the flow.
`onEvent`	`function`	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. Confirm the resource 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 determine whether resource creation succeeded or failed.

Dark mode for the Widget appearanceSend appearance to set the Widget color scheme to light or dark.

`username` and `holderId` objects

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

Client

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

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

Pre-filling increases payment conversionIn Fintoc’s internal testing, pre-filling the username raised payment conversion by 3%.

The username and holderId objects support these attributes:

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

Home

Resources

Payments

Transfers

Movements

Integrate the Widget on the web

Plain HTML integration

ES module integration

Methods of the Widget object

Configure the Widget

Payment initiation

Movements

Direct debit

`username` and `holderId` objects

​Plain HTML integration

​ES module integration

​Methods of the Widget object

​Configure the Widget

​Payment initiation

​Movements

​Direct debit

​username and holderId objects

Plain HTML integration

ES module integration

Methods of the Widget object

Configure the Widget

Payment initiation

Movements

Direct debit

`username` and `holderId` objects