> ## 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
### Plain HTML Integration
To integrate the Widget, you just need to include the Fintoc script on your HTML. The Fintoc script needs to be on each page where the Widget needs to be used.
```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`! Just use our `@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';
// 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
Once a `widget` object gets created, you can use its methods to interact with it. The available methods are `open`, `close` and `destroy`.
| Method | Description |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| widget.open() | The `open` method opens the Widget whenever it is called. |
| widget.hide() | The `hide` method closes the widget whenever it is called. It **does not destroy the widget instance**, it only hides it from the user. You can call the `open` method after the `hide` method and the widget will show again. |
| widget.destroy() | The `destroy` method removes the Widget instance from your application. If you want to re-open the widget after calling the `destroy` method, you will need to create another Widget instance using `Fintoc.create()`. |
**How to use the `widget.destroy()` method**
When using `Fintoc.create(args)`, an `iframe` gets embedded within your application. Sometimes (primarily when developing an SPA), you might need to remove this `iframe`. This can get done using the `destroy` method. If you then need to re-open the widget, you will need to create a new instance using the `Fintoc.create(args)` method once again.
## How to set up and deploy the widget
Depending on the product you're using, there's different ways to set up and deploy the widget on your front end.
When including the Fintoc `script` on your application (or after using the `getFintoc` method of the `@fintoc/fintoc-js` library), you will have access to the `Fintoc` class, that will allow you to create connections with a financial institution from within your application.
Note: remember to call the `.open()` method in order to raise 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,
})
```
| Parameter | Type | Description |
| :------------ | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| publicKey | string | The `publicKey` is used to identify your web application or web page within Fintoc. Links created with a `publicKey` will get assigned to the organization or user that owns said `publicKey`.
This token will determine whether you're using the sandbox or the production environment. Remember that the `publicKey` of the sandbox starts with `pk_test_`, while the production one starts with `pk_live_`. |
| holderType | string | The `holderType` parameter can be `business` or `individual`, and determines the type of account that will be connected to Fintoc. **This parameter is not required for the Payment Initiation product**. |
| product | string | The `product` parameter can be `movements`, `subscriptions`, `invoices`, or `payments`, and determines the product and type of **Link** that will be created. |
| country | string | The `country` parameter must be the `ISO 3166-1 alfa-2` code of the country to which you're trying to connect. It can be `cl` or `mx`. Defaults to `cl`. **This parameter is not required for the Payment Initiation product**. |
| institutionId | string | \* \*Optional\*\*. The `institutionId` parameter corresponds to the `id` of [a financial institution](/v2023-11-15/docs/payments/overview-payment-initiation/payment-initiation-countries-and-institutions). If included, said institution will be pre-selected. For example, the value `cl_banco_estado` would command the widget to open with Banco Estado by default. Before pre-selecting an institution, check the availability using the list institutions endpoint |
| username | string or object | \* \*Optional\*\*. The `username` pre-fills the username field when making a payment.
The attributes of the username object [are below](/v2023-11-15/docs/resources/widget/widget-web-integration#username-object). If a string is sent, it will take the default value for the editable attribute. |
| holderId | string or object | \* \*Optional\*\*. The`holderId` pre-fills the holderId field when connecting a link in the \*\*`Movements`\*\* product.
The attributes of the holderId object [are below](/v2023-11-15/docs/resources/widget/widget-web-integration#username-and-holderid-objects) . If a string is sent, it will take the default value for the editable attribute.
Only the `movements` product uses this parameter. |
| sessionToken | string | **Only used for the Payment Initiation product**
The `sessionToken` parameter corresponds to the token created by the backend when creating a [Checkout Session](https://dash.readme.com/go/fintoc?redirect=%2Fv2023-11-15%2Freference%2Fcreate-checkout-session) and it is used to deploy and configure the Widget. |
| webhookUrl | string | \* \*Only used for `movements` and `invoices` products\*\*, if you are integrating `payments` or `subscriptions` you don't need this.
The `webhookUrl` parameter corresponds to the URL that will get a request with the new **Link** after its successful creation, including its **link\_token**. |
| widgetToken | string | The `widgetToken` parameter corresponds to the token created by the backend that initializes and configures the widget.
Only the `subscriptions` product uses a `widgetToken` parameter. |
| onSuccess | function | The `onSuccess` parameter corresponds to a callback that will be called after the flow finishes successfully. |
| onExit | function | The `onExit` parameter corresponds to a callback that will be called after a user closes the Widget prematurely. |
| onEvent | function | The `onEvent` parameter corresponds to a callback that will be called every time after a user executes a meaningful action on the Widget. |
**Use the Widget callbacks and events correctly**
**Never** use the `onSuccess`, `onExit` or `onEvent` callbacks to get the state of the resource being created. You should **only** use these callbacks to handle the flow of your frontend application, **while waiting backend confirmation**, either via Webhooks or by exchanging some exchange token. Frontend events can also be used to generate metrics about general widget usage, but you should **never** rely solely on them to assume a resource was created or failed to be created.
### Username and holderId Objects
To pre-fill a username or a holderId and change the default values, you can send an object with the following attributes
```Text JSON theme={null}
username = {
value: "123456789",
editable: true
}
holderId = {
value: "123456789",
editable: true
}
```
**Using the pre-fill option boosts payment conversion**
Our testing has shown that using the pre-fill can boost conversion by around 3%
| Attribute | Type | Description |
| :-------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| value | string | The username or holderId that will be pre-filled on the widget. For the **`Payments`** product, in Chile you should input the user's RUT and in Mexico you should input the user's phone number.
When using **`Movements`**, you should input the business' RUT of the account that will be connected. |
| editable | bool | Whether the field is editable or not in the widget. By default it's set to `true`. |