> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Web Integration
> Reference to integrate the Widget on your web application or web page
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.
```html theme={null}
```
**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.
```shell theme={null}
npm install @fintoc/fintoc-js
```
The library exports an async `getFintoc` method that returns the `Fintoc` object.
```javascript theme={null}
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`.
| 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()` 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
```javascript Javascript theme={null}
const widget = Fintoc.create({
product,
publicKey,
sessionToken,
onSuccess,
onExit,
onEvent,
})
```
### Movements
```javascript Javascript theme={null}
const widget = Fintoc.create({
holderType,
product,
publicKey,
webhookUrl,
country,
institutionId,
linkToken,
onSuccess,
onExit,
onEvent,
})
```
### Direct Debit
```javascript Javascript theme={null}
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](/docs/payments/overview-payment-initiation/payment-initiation-countries-and-institutions). 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](/reference/main-resources/institutions/institutions-list). |
| username | string or object | Pre-fills the username field when making a payment. See the attributes of the `username` object [below](#username-and-holderid-objects). 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](#username-and-holderid-objects). 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](/reference/payments-api/checkout-sessions/checkout-sessions-create). 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 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:
```javascript theme={null}
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%.
| 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`. |