> ## 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.
# Integra el Widget en la web
> Integra el Widget de Fintoc en tu aplicación web o sitio para que tus clientes vinculen su cuenta bancaria o completen un pago sin salir de tu página.
Incorpora el Widget de Fintoc en una aplicación web mediante una etiqueta `script` de HTML o un módulo ES. Esta página también cubre los métodos del Widget, los parámetros de configuración y los callbacks.
## Integración con HTML plano
Para integrar el Widget, incluye el script de Fintoc en tu página HTML. Incluye el script en cada página donde uses el Widget.
```html Client 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 la librería `@fintoc/fintoc-js` como un módulo ES a través de `npm`.
```bash Client theme={null}
npm install @fintoc/fintoc-js
```
La librería exporta la función asíncrona `getFintoc`. Esta función devuelve el objeto `Fintoc`.
```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();
```
## Métodos del objeto Widget
Una vez que creas una instancia del Widget, usa sus métodos `open`, `hide` y `destroy` para controlarla:
| Método | Descripción |
| :----------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| `widget.open()` | Abre el Widget. |
| `widget.hide()` | Cierra el Widget sin destruir la instancia del Widget. El Widget permanece oculto hasta que llames a `widget.open()` de nuevo. |
| `widget.destroy()` | Elimina la instancia del Widget de tu aplicación. Para volver a abrir el Widget, crea otra instancia con `Fintoc.create()`. |
**Cómo usar el método `widget.destroy()`**
Al usar `Fintoc.create(args)`, se incrusta un `iframe` dentro de tu aplicación. En una aplicación de una sola página, podrías necesitar remover ese `iframe`. Llama a `widget.destroy()` para remover el `iframe`. Para volver a abrir el Widget, crea una nueva instancia con `Fintoc.create(args)`.
## Configura el Widget
Cada producto requiere distintos parámetros de configuración del Widget.
Al cargar el `script` de Fintoc, tu aplicación obtiene acceso al objeto `Fintoc`. La función `getFintoc` de `@fintoc/fintoc-js` devuelve el mismo objeto. Usa `Fintoc.create()` para crear una instancia del Widget para tu producto.
**Abre el Widget**
Llama a `widget.open()` para abrir el 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,
});
```
Configura el Widget con estos parámetros:
| Parámetro | Tipo | Descripción |
| --------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicKey` | `string` | Identificador de tu aplicación web o página web dentro de Fintoc. Fintoc asigna cada `Link` creado con la clave al dueño de esa clave. Las claves de sandbox empiezan con `pk_test_`, y las de producción con `pk_live_`. |
| `holderType` | `string` | Tipo de cuenta que se conectará a Fintoc. Uno de `business` o `individual`. No se requiere para Payment Initiation. |
| `product` | `string` | Producto y tipo de `Link` que se creará. Uno de `movements`, `subscriptions`, `invoices`, o `payments`. |
| `country` | `string` | Código de país ISO 3166-1 alfa-2 de dos letras. Uno de `cl` (Chile) o `mx` (México). Por defecto es `cl`. No se requiere para Payment Initiation. |
| `appearance` | `object` | Esquema de color del Widget. Contiene un campo `theme` con el valor `light` o `dark`. Por defecto es `light`. Por ejemplo, `appearance: { theme: 'dark' }`. |
| `institutionId` | `string` | Identificador de [una institución financiera](/es/guides/payments/overview-payment-initiation/payment-initiation-countries-and-institutions). Si se incluye, Fintoc preselecciona esa institución. Por ejemplo, `cl_banco_estado` abre el Widget con Banco Estado seleccionado. Verifica la disponibilidad con el [endpoint de listar instituciones](/es/api/main-resources/institutions/institutions-list) antes de preseleccionar una institución. |
| `username` | `string` u `object` | Valor que pre-llena el campo `username` al hacer un pago. Consulta los [atributos del objeto `username`](#objetos-username-y-holderid). Un string configura `editable` con su valor por defecto de `true`. |
| `holderId` | `string` u `object` | Valor que pre-llena `holderId` al conectar un `Link` para `movements`. Consulta los [atributos del objeto `holderId`](#objetos-username-y-holderid). Un string configura `editable` con su valor por defecto de `true`. Solo `movements` usa este parámetro. |
| `sessionToken` | `string` | Token que tu backend crea con una [Checkout Session](/es/api/payments-api/checkout-sessions/checkout-sessions-create). El Widget usa `sessionToken` para cargar y configurar el flujo de pago. Solo `payments` usa este parámetro. |
| `webhookUrl` | `string` | URL que recibe una solicitud después de que Fintoc crea un `Link`. La solicitud incluye el `link_token` del objeto `Link`. Solo `movements` e `invoices` usan este parámetro. |
| `widgetToken` | `string` | Token que tu backend crea para inicializar y configurar el Widget. Solo `subscriptions` usa este parámetro. |
| `onSuccess` | `function` | Callback que Fintoc llama después de que el flujo termina exitosamente. |
| `onExit` | `function` | Callback que Fintoc llama después de que tu cliente cierra el Widget antes de completar el flujo. |
| `onEvent` | `function` | Callback que Fintoc llama cada vez que tu cliente realiza una acción registrada en el Widget. |
**Usa los callbacks y eventos del Widget correctamente**
Nunca uses los callbacks `onSuccess`, `onExit` u `onEvent` para leer el estado del recurso que se está creando. Usa estos callbacks solo para manejar el flujo de tu aplicación frontend mientras esperas la confirmación del backend. Confirma el recurso mediante webhooks o intercambiando un token de confirmación. También puedes usar los eventos del frontend para generar métricas de uso del Widget. Nunca confíes únicamente en los eventos del frontend para determinar si la creación del recurso tuvo éxito o falló.
**Modo oscuro para la apariencia del Widget**
Envía `appearance` para configurar el esquema de color del Widget en `light` o `dark`.
## Objetos `username` y `holderId`
Para pre-llenar `username` o `holderId` y sobrescribir los valores por defecto, envía un objeto con estos atributos:
```javascript Client theme={null}
const username = {
value: '11.111.111-1',
editable: true,
};
const holderId = {
value: '11.111.111-1',
editable: true,
};
```
**Usar la opción de pre-llenado mejora la conversión de pagos**
En las pruebas internas de Fintoc, pre-llenar el username aumentó la conversión de pagos en un 3%.
Los objetos `username` y `holderId` admiten estos atributos:
| Atributo | Tipo | Descripción |
| ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `value` | `string` | Valor que se pre-llenará en el Widget. Para `payments`, ingresa el RUT (Chile) o el número de teléfono (México). Para `movements`, ingresa el RUT de la empresa dueña de la cuenta que conectas. |
| `editable` | `boolean` | Si el campo es editable en el Widget. Por defecto es `true`. |