> ## 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 for integrating the Fintoc Widget on the legacy v2023-11-15 API into your web application or website, from script load to onSuccess handling.
### Plain HTML integration
Include the Fintoc script in the HTML of each page that uses the Widget.
```html theme={null}
```
**window\.onload**
Wait for the browser to load the `script` before calling its functions. Use the native `window.onload` browser event to avoid errors.
### ES module integration
You can also use the `@fintoc/fintoc-js` library to load the Widget as an ES module through `npm`.
```bash theme={null}
npm install @fintoc/fintoc-js
```
The library exports the asynchronous `getFintoc` method, which returns the `Fintoc` object.
```javascript theme={null}
import { getFintoc } from '@fintoc/fintoc-js';
// You can read more about the parameters below
const options = { ... };
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` object, use its `open`, `hide`, and `destroy` methods to interact with it:
| Method | Description |
| :----------------- | :----------------------------------------------------------------------------------------------------------------------- |
| `widget.open()` | Opens the Widget. |
| `widget.hide()` | Hides the Widget without destroying the instance. Call `open` after `hide` to display the Widget again. |
| `widget.destroy()` | Removes the Widget instance from your application. To reopen the Widget, create another instance with `Fintoc.create()`. |
**How to use the `widget.destroy()` method**
`Fintoc.create(args)` embeds an `iframe` in your application. When developing a single-page application (SPA), call `destroy` to remove this `iframe`. To reopen the Widget, create a new instance with `Fintoc.create(args)`.
## How to set up and deploy the widget
The setup and deployment options depend on the product you use.
Include the Fintoc `script` in your application or call `getFintoc` from the `@fintoc/fintoc-js` library. You can then use the `Fintoc` class to connect to a financial institution from your application.
Call `open()` to display 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,
link_token,
onSuccess,
onExit,
onEvent,
})
```
### Direct Debit
```javascript Javascript theme={null}
const widget = Fintoc.create({
holderType,
product,
publicKey,
country,
institutionId,
widgetToken,
onSuccess,
onExit,
onEvent,
})
```
Use the following parameters to configure the Widget:
| Parameter | Type | Description |
| :-------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `publicKey` | string | Identifies your web application or web page in Fintoc. Fintoc assigns `Link` objects created with this key to the organization or user that owns the key.
The prefix determines the environment: `pk_test_` for sandbox and `pk_live_` for production. |
| `holderType` | string | Type of account to connect to Fintoc. One of `business` or `individual`. Payment Initiation does not use this parameter. |
| `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` or `mx`. Defaults to `cl`. Payment Initiation does not use this parameter. |
| `institutionId` | string | Identifier of [a financial institution](/v2023-11-15/guides/payments/overview-payment-initiation/payment-initiation-countries-and-institutions) to preselect. For example, `cl_banco_estado` opens the Widget with Banco Estado selected. Check availability with the [List institutions endpoint](/v2023-11-15/api/main-resources/institutions/list-institutions). |
| `username` | string or object | Username to prefill when making a payment. To customize its value and editability, use the [username object](#username-and-holderid-objects). A string uses the default value of the `editable` attribute. |
| `holderId` | string or object | Account holder identifier to prefill when connecting a `Link`. To customize its value and editability, use the [`holderId` object](#username-and-holderid-objects). A string uses the default value of the `editable` attribute. Only the `movements` product uses this parameter. |
| `sessionToken` | string | Token your backend creates with a [Checkout Session](/v2023-11-15/api/payment-initiation-api/checkout-sessions/create-checkout-session) to initialize and configure the Widget. Only Payment Initiation uses this parameter. |
| `webhookUrl` | string | URL that receives a request containing the new `Link` and its `link_token` after creation. Only the `movements` and `invoices` products use this parameter. |
| `widgetToken` | string | Token your backend creates to initialize and configure the Widget. Only the `subscriptions` product uses this parameter. |
| `onSuccess` | function | Callback invoked after the flow finishes successfully. |
| `onExit` | function | Callback invoked when a user closes the Widget before completing the flow. |
| `onEvent` | function | Callback invoked after a user performs a meaningful action in the Widget. |
**Use the Widget callbacks and events correctly**
Do not use the `onSuccess`, `onExit`, or `onEvent` callbacks to determine the resource state. Use these callbacks only to manage your frontend flow while your backend confirms the state through webhooks or a token exchange. You can also use frontend events to measure Widget usage, but do not rely on these events to determine whether Fintoc created the resource.
### Username and `holderId` objects
To prefill a username or `holderId` and customize the default values, pass an object with these attributes:
```javascript JSON theme={null}
username = {
value: "123456789",
editable: true
}
holderId = {
value: "123456789",
editable: true
}
```
**Prefilling can improve payment conversion**
Fintoc testing shows that prefilling these values can increase payment conversion by approximately 3%.
| Attribute | Type | Description |
| :--------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | string | Username or `holderId` to prefill in the Widget. For the `payments` product, enter the user's Chilean tax ID (RUT) in Chile or phone number in Mexico.
For the `movements` product, enter the RUT of the business account you want to connect. |
| `editable` | bool | Whether the field is editable in the Widget. Defaults to `true`. |