> ## 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.
# Integración Web
> Referencia para integrar el Widget en tu aplicación web o página web
### Integración con HTML plano
Para integrar el Widget, solo necesitas incluir el script de Fintoc en tu HTML. El script de Fintoc debe estar en cada página donde se necesite usar el Widget.
```html theme={null}
```
**window\.onload**
Recuerda que, al importar un `script` de JavaScript, si intentas usar funciones antes de que el navegador cargue el `script`, se lanzará un error. Puedes solucionar esto usando el evento nativo del navegador `window.onload`.
### Integración como módulo ES
¡También puedes usar el Widget como un módulo ES a través de `npm`! ¡Solo usa nuestra librería `@fintoc/fintoc-js`!
```shell theme={null}
npm install @fintoc/fintoc-js
```
¡La librería exporta un método *async* `getFintoc` que devuelve el objeto `Fintoc`!
```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();
```
## Métodos del objeto Widget
Una vez que se crea un objeto `widget`, puedes usar sus métodos para interactuar con él. Los métodos disponibles son `open`, `close` y `destroy`.
| Método | Descripción |
| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| widget.open() | El método `open` abre el Widget cuando se llama. |
| widget.hide() | El método `hide` cierra el widget cuando se llama. **No destruye la instancia del widget**, solo lo oculta del usuario. Puedes llamar al método `open` después del método `hide` y el widget se mostrará nuevamente. |
| widget.destroy() | El método `destroy` elimina la instancia del Widget de tu aplicación. Si quieres volver a abrir el widget después de llamar al método `destroy`, necesitarás crear otra instancia del Widget usando `Fintoc.create()`. |
**Cómo usar el método `widget.destroy()`**
Al usar `Fintoc.create(args)`, se incrusta un `iframe` dentro de tu aplicación. A veces (principalmente al desarrollar una SPA), podrías necesitar remover este `iframe`. Esto se puede hacer usando el método `destroy`. Si luego necesitas volver a abrir el widget, necesitarás crear una nueva instancia usando el método `Fintoc.create(args)` una vez más.
## Cómo configurar y desplegar el widget
Dependiendo del producto que estés usando, hay distintas formas de configurar y desplegar el widget en tu frontend.
Al incluir el `script` de Fintoc en tu aplicación (o después de usar el método `getFintoc` de la librería `@fintoc/fintoc-js`), tendrás acceso a la clase `Fintoc`, que te permitirá crear conexiones con una institución financiera desde dentro de tu aplicación.
Nota: recuerda llamar al método `.open()` para levantar el 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,
})
```
| Parámetro | Tipo | Descripción |
| ------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| publicKey | string | El `publicKey` se usa para identificar tu aplicación web o página web dentro de Fintoc. Los Links creados con un `publicKey` se asignarán a la organización o usuario que sea dueño de dicho `publicKey`.
Este token determinará si estás usando el sandbox o el entorno de producción. Recuerda que el `publicKey` del sandbox empieza con `pk_test_`, mientras que el de producción empieza con `pk_live_`. |
| holderType | string | El parámetro `holderType` puede ser `business` o `individual`, y determina el tipo de cuenta que se conectará a Fintoc. **Este parámetro no es requerido para el producto Payment Initiation**. |
| product | string | El parámetro `product` puede ser `movements`, `subscriptions`, `invoices`, o `payments`, y determina el producto y tipo de **Link** que se creará. |
| country | string | El parámetro `country` debe ser el código `ISO 3166-1 alfa-2` del país al que estás intentando conectarte. Puede ser `cl` o `mx`. Por defecto es `cl`. **Este parámetro no es requerido para el producto Payment Initiation**. |
| appearence | object | La apariencia del Widget de Fintoc para estar en modo Light o Dark. Incluye el objeto `theme` con las opciones `light` (por defecto) o `dark`. Ejemplo para Dark Mode: `appearence: {theme: "dark"}` |
| institutionId | string | \* *Opcional*\*. El parámetro `institutionId` corresponde al `id` de [una institución financiera](/es/docs/payments/overview-payment-initiation/payment-initiation-countries-and-institutions). Si se incluye, dicha institución será preseleccionada. Por ejemplo, el valor `cl_banco_estado` ordenaría al widget abrirse con Banco Estado por defecto. Antes de preseleccionar una institución, verifica la disponibilidad usando el [endpoint list institutions](/es/reference/main-resources/institutions/institutions-list) |
| username | string u object | \* *Opcional*\*. El `username` pre-llena el campo de username al hacer un pago.
Los atributos del objeto username [están abajo](/es/docs/resources/widget/widget-web-integration#username-object). Si se envía un string, tomará el valor por defecto para el atributo editable. |
| holderId | string u object | \* *Opcional*\*. El `holderId` pre-llena el campo holderId al conectar un link en el producto **`Movements`**.
Los atributos del objeto holderId [están abajo](/es/docs/resources/widget/widget-web-integration#username-and-holderid-objects). Si se envía un string, tomará el valor por defecto para el atributo editable.
Solo el producto `movements` usa este parámetro. |
| sessionToken | string | **Solo se usa para el producto Payment Initiation**
El parámetro `sessionToken` corresponde al token creado por el backend al crear un [Checkout Session](https://dash.readme.com/go/fintoc?redirect=%2Fv2023-11-15%2Freference%2Fcreate-checkout-session) y se usa para desplegar y configurar el Widget. |
| webhookUrl | string | \* \*Solo se usa para los productos `movements` e `invoices`\*\*, si estás integrando `payments` o `subscriptions` no necesitas esto.
El parámetro `webhookUrl` corresponde a la URL que recibirá una solicitud con el nuevo **Link** después de su creación exitosa, incluyendo su **link\_token**. |
| widgetToken | string | El parámetro `widgetToken` corresponde al token creado por el backend que inicializa y configura el widget.
Solo el producto `subscriptions` usa un parámetro `widgetToken`. |
| onSuccess | function | El parámetro `onSuccess` corresponde a un callback que se llamará después de que el flujo termine exitosamente. |
| onExit | function | El parámetro `onExit` corresponde a un callback que se llamará después de que un usuario cierre el Widget prematuramente. |
| onEvent | function | El parámetro `onEvent` corresponde a un callback que se llamará cada vez que un usuario ejecute una acción significativa en el Widget. |
**Usa los callbacks y eventos del Widget correctamente**
**Nunca** uses los callbacks `onSuccess`, `onExit` u `onEvent` para obtener el estado del recurso que se está creando. **Solo** debes usar estos callbacks para manejar el flujo de tu aplicación frontend, **mientras esperas la confirmación del backend**, ya sea vía Webhooks o intercambiando algún exchange token. Los eventos del frontend también pueden usarse para generar métricas sobre el uso general del widget, pero **nunca** debes confiar únicamente en ellos para asumir que un recurso se creó o falló en crearse.
**Nuevo Dark Mode para la apariencia del Widget**
Puedes enviar el parámetro `appearence` para definir si el flujo del Widget estará en modo Light o Dark.
### Objetos Username y holderId
Para pre-llenar un username o un holderId y cambiar los valores por defecto, puedes enviar un objeto con los siguientes atributos
```Text JSON theme={null}
username = {
value: "123456789",
editable: true
}
holderId = {
value: "123456789",
editable: true
}
```
**Usar la opción de pre-llenado mejora la conversión de pagos**
Nuestras pruebas han demostrado que usar el pre-llenado puede mejorar la conversión en alrededor de un 3%
| Atributo | Tipo | Descripción |
| -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| value | string | El username o holderId que se pre-llenará en el widget. Para el producto **`Payments`**, en Chile debes ingresar el RUT del usuario y en México debes ingresar el número de teléfono del usuario.
Al usar **`Movements`**, debes ingresar el RUT empresarial de la cuenta que se conectará. |
| editable | bool | Si el campo es editable o no en el widget. Por defecto está configurado como `true`. |