> ## 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.
# Integrate the Widget on the web
> Integrate the Widget into your web application or web page
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.
```html Client theme={null}
```
**window\.onload**
The 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`.
```shell Client theme={null}
npm install @fintoc/fintoc-js
```
The library exports the asynchronous `getFintoc` function. This function returns the `Fintoc` object.
```javascript Client 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
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()` method**
Calling `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)`.
## Configure the Widget
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 Widget**
Call `widget.open()` to open the Widget.
### Payment initiation
```javascript Client theme={null}
const widget = Fintoc.create({
product,
publicKey,
sessionToken,
onSuccess,
onExit,
onEvent,
});
```
### Movements
```javascript Client theme={null}
const widget = Fintoc.create({
holderType,
product,
publicKey,
webhookUrl,
country,
institutionId,
linkToken,
onSuccess,
onExit,
onEvent,
});
```
### Direct debit
```javascript Client theme={null}
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](/guides/payments/overview-payment-initiation/payment-initiation-countries-and-institutions). 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](/api/main-resources/institutions/institutions-list) before preselecting an institution. |
| `username` | `string` or `object` | Value that pre-fills the `username` field when making a payment. See the [`username` object attributes](#username-and-holderid-objects). 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](#username-and-holderid-objects). 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](/api/payments-api/checkout-sessions/checkout-sessions-create). 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 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. 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 appearance**
Send `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:
```javascript Client theme={null}
const username = {
value: '11.111.111-1',
editable: true,
};
const holderId = {
value: '11.111.111-1',
editable: true,
};
```
**Pre-filling increases payment conversion**
In 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`. |