Hay dos etapas en el producto Direct Debit:

Tu usuario debe primero autorizar a Fintoc a debitar su cuenta. A esta autorización la llamamos Subscription.
Una vez que el usuario autoriza a Fintoc, puedes crear cargos para debitar la cuenta de tu usuario.

El siguiente diagrama muestra cómo Fintoc interactúa tanto con tu backend como con tu frontend en ambas etapas.

Flujo de autorización

Antes de que puedas comenzar a crear cargos, tu usuario debe autorizar a Fintoc a debitar su cuenta. Esta autorización es lo que llamamos Subscription. Como en la mayoría de los productos de Fintoc, tu usuario debe pasar por el Widget para crear la suscripción. Hay tres pasos para crear suscripciones usando Fintoc:

En tu backend, crea un SubscriptionIntent usando tu Secret Key
Abre el widget en tu frontend usando tu Public Key
Maneja los eventos posteriores a la suscripción

Crear un Subscription Intent

Para iniciar el proceso de suscripción, primero debes crear un Subscription Intent desde tu backend.

curl --request POST "https://api.fintoc.com/v1/subscription_intents" \
--header 'Authorization: sk_live_0000000000000000' \
--header 'Content-Type: application/json'

La respuesta debería verse así:

{
  "id": "si_m7N9rAWJS9dWDKEe",
  "object": "subscription_intent",
  "widget_token": "si_XXXXXXXX_sec_YYYYYYYY",
  "status": "created",
  "bank_account": null,
  "subscription": null,
  "business_profile": {
    "name": "Merchant Name"
  },
  "created_at": "2021-11-11T02:29:16Z"
}

Observa que el Subscription Intent incluye un widget_token. Este token es necesario para abrir el Widget en el frontend de tu aplicación. La siguiente sección contiene más detalles al respecto.

Business Profile NamePuedes enviar business_profile.name para personalizar el nombre que se mostrará como la “Empresa Destinataria” en las pantallas del widget.

Una vez creado el Subscription Intent, debes enviar su widget_token a tu frontend y usarlo para configurar el widget y el flujo que seguirá el usuario.

Widget TokenEl widget_token evita que tu aplicación tenga que enviar datos sensibles a Fintoc desde tu frontend. El token es temporal y expirará 10 minutos después de su creación.

Aquí tienes un ejemplo del widget configurado con el widget_token:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Fintoc Demo</title>
    <script src="https://js.fintoc.com/v1/"></script>
  </head>
  <body>
    <script>
      window.onload = () => {
        const widget = Fintoc.create({
          holderType: 'individual',
          widgetToken: 'si_XXXXXXXX_sec_YYYYYYYY',
          product: 'subscriptions',
          publicKey: 'pk_live_0000000000',
          onSuccess: () => {},
        };
        widget.open();
      });
      </script>
  </body>
</html>

Usa los callbacks y eventos del Widget correctamenteNunca uses los callbacks onSuccess, onExit u onEvent para obtener el estado de la Subscription que se está creando. Debes usar estos callbacks solo para manejar el flujo de tu aplicación frontend, mientras esperas la confirmación del backend mediante Webhooks. Los eventos del frontend también pueden usarse para generar métricas sobre el uso general del widget, pero nunca debes basarte únicamente en ellos para asumir que una Subscription fue creada o falló al crearse.

Para leer más sobre el widget y su configuración, ve a la sección widget.

Manejar eventos posteriores a la suscripción

Una vez que un Subscription Intent termina, manejas el resultado de la suscripción en tu frontend y completas la suscripción en tu backend. Para tu frontend usarás el callback del widget, y para tu backend usarás los eventos enviados por webhooks.

Manejar el resultado de la suscripción en tu frontend

Una vez que un Subscription Intent termina exitosamente, el widget ejecuta el callback onSuccess. Necesitas pasarle esta función al widget al momento de crearlo. Con este callback puedes decidir qué hacer con el frontend de tu usuario una vez completada la suscripción, por ejemplo:

Redirigir al usuario a una vista posterior a la suscripción
Mostrar al usuario una pantalla de éxito.

Manejar errores

No solo necesitas manejar el caso exitoso, ya que las suscripciones también pueden fallar. Por ejemplo, tu cliente abandonó el proceso antes de completar la suscripción. Cuando una suscripción falla o es rechazada por tu cliente, el widget ejecuta el callback onExit. Con este callback puedes manejar errores en tu frontend. Por ejemplo, puedes invitar a tu cliente a reintentar el proceso. Para obtener la razón del error puedes acceder al callback onExit creando una instancia de él. Aquí un ejemplo:

onExit: function onExit(errorReason) {
  console.log(errorReason);
}

Almacenar la suscripción creada

Para recibir notificaciones sobre el proceso de suscripción, primero debes haber creado un Webhook Endpoint en Fintoc y asignarle los eventos que quieres recibir. Es muy importante que te suscribas al evento subscription_intent.succeeded. Además, debes almacenar el subscription_id incluido en un lugar seguro al que puedas acceder más tarde. El subscription_id es necesario para crear Charges más adelante. El proceso de suscripción puede generar 3 eventos distintos que se envían a tu webhook endpoint:

Evento	Descripción
`subscription_intent.succeeded`	Evento que se dispara cuando un subscription intent se valida como exitoso. El `subscription_intent` incluye el objeto `subscription` resultante.
`subscription_intent.failed`	Evento que se dispara cuando un subscription intent falla por un problema con el banco o con Fintoc.
`subscription_intent.rejected`	Evento que se dispara cuando un subscription intent es rechazado por el usuario. Esto puede suceder cuando el usuario rechaza el paso de MFA o lo ingresa mal.

Webhook del backend vs onSuccess del widgetEs muy importante que esperes el evento del webhook en tu backend para terminar el proceso. Nunca debes finalizar el flujo basándote únicamente en la función onSuccess del widget. Algunos usuarios pueden cerrar el widget antes de que el callback que envía el webhook a tu backend se ejecute.

Esperar la activación de la suscripción

La suscripción creada comienza con un estado pending. Esto indica que la suscripción se creó correctamente, pero todavía no se pueden crear cargos. Primero, Fintoc necesita que el banco confirme que la suscripción está operativa. Una nueva suscripción puede tardar hasta 5 días hábiles en estar operativa. Una vez que una suscripción se valida como lista para recibir cargos, se dispara un evento subscription.activated y se envía por webhooks. Si por alguna razón el banco informa a Fintoc que una suscripción ha sido cancelada, se disparará un evento subscription.canceled.

Evento	Descripción
`subscription.activated`	Evento que se dispara cuando el banco ha confirmado que la suscripción está lista para aceptar cargos.
`subscription.canceled`	Evento que se dispara cuando el banco informa a Fintoc que la suscripción ha sido cancelada.

¿Qué sucede cuando el usuario crea un nuevo Subscription Intent con la misma cuenta bancaria?Cada flujo verifica si existen suscripciones previas creadas entre el usuario y tu organización. Si ya existe una activa, los usuarios verán una pantalla de éxito como confirmación y se enviará el evento subscription_intent.succeeded con el subscription.id activo.

Flujo de cargos

Crear un Charge

Fintoc usa el objeto Charge para representar un pago de suscripción. Desde tu backend, crea un Charge con el monto, la moneda y el subscription_id que obtuviste en el paso de autorización. También puedes agregar el objeto business_profile para facturación por categoría. Aquí un ejemplo:

curl --request POST "https://api.fintoc.com/v1/charges" \
--header 'Authorization: sk_live_xxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 1000,
  "currency": "CLP",
  "subscription_id": "xxxxxxxxx",
  "business_profile": {
    "name": "Merchant Name",
    "tax_id": "967224006",
    "category": "611090"
  }
}'

La respuesta debería verse así:

{
  "id": "ch_m7N9rAWJS9dWDKEe",
  "object": "charge",
  "amount": 1000,
  "currency": "CLP",
  "status": "pending",
  "failure_code": null,
  "metadata": {},
  "created_at": "2021-11-11T02:29:16Z",
}

Confirmación del cargo

Un cargo puede tardar hasta 2 días hábiles antes de tener confirmación de su éxito o falla:

Al crearse, los cargos tienen un estado inicial de pending.
Fintoc procesa los cargos una vez al día a las 2 pm. Cuando esto ocurre, el cargo pasa a in_progress y ya no se puede cancelar. Los cargos creados después de las 2 pm (hora de CL) se procesan el siguiente día hábil.
Durante los siguientes 2 días hábiles, el cargo pasa a succeeded o failed dependiendo del banco del usuario.
Tu usuario ve el cargo reflejado en su estado de cuenta bancario 2 días hábiles después de creado el cargo. Tu usuario sabrá si el cargo fue exitoso antes de que el banco notifique a Fintoc.
Los cargos se transfieren a tu cuenta bancaria el siguiente día hábil después de que pasaron al estado exitoso.

Las fallas pueden ocurrir por varias razones, como fondos insuficientes, que el monto cobrado sea mayor al monto autorizado, o que el cliente desactive la autorización desde su cuenta bancaria.

Webhooks de cargos

Una vez que se completa el cargo, te enviaremos un evento con charge como tipo a través de un webhook. Para suscribirte al evento, primero debes haber creado un Webhook Endpoint en Fintoc y asignarle los eventos que quieres recibir. Debes suscribirte a estos eventos, ya que puedes usarlos para identificar los cargos exitosos de los fallidos.

Evento	Descripción
`charge.succeeded`	Evento que se dispara cuando un cargo se valida como exitoso.
`charge.failed`	Evento que se dispara cuando un cargo falla debido a fondos insuficientes, que el monto cobrado sea mayor al autorizado, o que el usuario desactive la autorización.

Charge Succeeded vs transferencia de fondosUn cargo se marca como exitoso cuando el banco confirma a Fintoc que ya se le ha cobrado al usuario el monto especificado. Esto no significa que esos fondos ya estén en la cuenta de tu organización. Fintoc tiene 1 día hábil para transferir ese dinero a tu cuenta.

Recibir fondos en tu cuenta

Una vez que creas un cargo a la cuenta de tu usuario, tomará de 3 a 4 días hábiles que esté disponible en tu cuenta bancaria. Esto depende principalmente de si el cargo se crea antes/después del horario de corte bancario. El esquema básico de tiempos es:

Veamos un ejemplo de un cargo creado a las 11:00 AM, antes del horario de corte bancario (02:00 PM):

Ahora, veamos otro ejemplo de un cargo creado a las 09:00 PM, después del horario de corte bancario (02:00 PM):

Bancos disponibles

Nombre	id
Banco de Chile	`cl_banco_de_chile`
Banco Scotiabank	`cl_banco_scotiabank`
Banco Itaú	`cl_banco_itau`
Banco Bci	`cl_banco_bci`
Banco Falabella	`cl_banco_falabella`
Banco Santander	`cl_banco_santander`
Banco Estado	`cl_banco_estado`

Inicio

Recursos

Pagos

Transferencias

Domiciliación bancaria

Movimientos

Flujo de integración

Flujo de autorización

Crear un Subscription Intent

Abrir el widget para Subscriptions

Manejar eventos posteriores a la suscripción

Manejar el resultado de la suscripción en tu frontend

Manejar errores

Almacenar la suscripción creada

Esperar la activación de la suscripción

Flujo de cargos

Crear un Charge

Confirmación del cargo

Webhooks de cargos

Recibir fondos en tu cuenta

Bancos disponibles

​Flujo de autorización

​Crear un Subscription Intent

​Abrir el widget para Subscriptions

​Manejar eventos posteriores a la suscripción

​Manejar el resultado de la suscripción en tu frontend

​Manejar errores

​Almacenar la suscripción creada

​Esperar la activación de la suscripción

​Flujo de cargos

​Crear un Charge

​Confirmación del cargo

​Webhooks de cargos

​Recibir fondos en tu cuenta

​Bancos disponibles

Flujo de autorización

Crear un Subscription Intent

Abrir el widget para Subscriptions

Manejar eventos posteriores a la suscripción

Manejar el resultado de la suscripción en tu frontend

Manejar errores

Almacenar la suscripción creada

Esperar la activación de la suscripción

Flujo de cargos

Crear un Charge

Confirmación del cargo

Webhooks de cargos

Recibir fondos en tu cuenta

Bancos disponibles