Tipos de eventos

Fintoc envía un evento de webhook cada vez que cambia un recurso de tu cuenta. Los nombres de los eventos siguen el patrón resource.event, y el campo data del evento lleva el recurso afectado. Para conocer el envoltorio que acompaña a cada evento, revisa el objeto Event. Para construir un endpoint que reciba eventos, sigue la guía de webhooks, que cubre la validación de firmas y el esquema de reintentos.

No puedes suscribirte al evento link.created con un webhook endpoint. Para recibir el evento, pasa la URL de tu backend cuando configures el widget.

Hoy Fintoc envía los siguientes tipos de eventos y agrega nuevos con el tiempo, así que ignora cualquier tipo que tu integración no reconozca:

Tipo de evento	`data.object`	Descripción
`account.refresh_intent.succeeded`	`refresh_intent`	Se dispara cuando Fintoc actualiza una `Account` con los últimos movimientos disponibles del banco.
`account.refresh_intent.failed`	`refresh_intent`	Se dispara cuando Fintoc no puede actualizar los movimientos de una `Account`. Disponible solo en planes Refresh On Demand.
`account.refresh_intent.rejected`	`refresh_intent`	Se dispara cuando Fintoc no puede actualizar los movimientos de una `Account` porque las credenciales del `Link` no son válidas. Disponible solo en planes Refresh On Demand.
`account.refresh_intent.movements_removed`	Sin campo `object`	Se dispara cuando el banco detrás de un `Link` elimina movimientos, y lleva `account_id` y `movements_removed` con los ids de los movimientos eliminados. Activa estas notificaciones desde tu dashboard.
`account.refresh_intent.movements_modified`	Sin campo `object`	Se dispara cuando el banco detrás de un `Link` modifica movimientos, y lleva `account_id` y `movements_changed` con los objetos `movement` completos que cambiaron. Activa estas notificaciones desde tu dashboard.
`account_number.deleted`	`account_number`	🇲🇽 Se dispara cuando se elimina un account number, ya sea a petición tuya o porque Fintoc lo purgó por estar inactivo.
`account_verification.succeeded`	`account_verification`	Se dispara cuando Fintoc obtiene la información del titular de la cuenta destino.
`account_verification.failed`	`account_verification`	Se dispara cuando Fintoc no puede obtener la información del titular de la cuenta destino.
`checkout_session.finished`	`checkout_session`	Se dispara cuando un cliente completa el flujo de pago. El payload lleva la `CheckoutSession`, incluyendo el estado final del pago.
`checkout_session.expired`	`checkout_session`	Se dispara cuando un cliente abandona el flujo de pago antes de finalizar.
`dispute.waiting_documentation`	`dispute`	Se dispara cuando tu cliente disputa un pago con tarjeta ante su emisor. Envía tu evidencia antes de `documentation_upload_deadline` o pierdes la disputa por defecto.
`dispute.in_review`	`dispute`	Se dispara cuando envías la disputa a revisión y el emisor empieza a evaluar tu evidencia.
`dispute.won`	`dispute`	Se dispara cuando el emisor resuelve la disputa a tu favor y los fondos se quedan contigo.
`dispute.lost`	`dispute`	Se dispara cuando el emisor resuelve la disputa a favor de tu cliente y los fondos vuelven a él.
`dispute.expired`	`dispute`	Se dispara cuando `documentation_upload_deadline` vence sin evidencia enviada. Pierdes la disputa.
`entity.onboarding.approved`	`onboarding_process`	Se dispara cuando una `Entity` aprueba la revisión de Know Your Customer. Ya puedes crear cuentas para esa `Entity`.
`entity.onboarding.rejected`	`onboarding_process`	Se dispara cuando una `Entity` no aprueba la revisión de Know Your Customer. Crea un nuevo onboarding para reintentar.
`invoice.created`	`invoice`	Se dispara cuando Fintoc crea una invoice.
`invoice.finalized`	`invoice`	Se dispara cuando Fintoc finaliza una invoice y la invoice queda lista para pagarse.
`invoice.paid`	`invoice`	Se dispara en toda transición a `paid`, ya sea que Fintoc haya cobrado la invoice o que tú la hayas marcado como pagada fuera de Fintoc.
`invoice.payment_created`	`invoice`	Se dispara cuando comienza un pago de una invoice, ya sea desde un cobro automático o desde tu cliente usando el `hosted_invoice_url`.
`invoice.payment_succeeded`	`invoice`	Se dispara cuando un intento de pago de una invoice resulta exitoso.
`invoice.payment_failed`	`invoice`	Se dispara cuando falla un intento de pago de una invoice.
`invoice.upcoming`	`invoice`	Se dispara antes del siguiente ciclo de facturación de una suscripción, como anticipo de la invoice que Fintoc está por crear. Revisa Anticipos de invoice.
`invoice.voided`	`invoice`	Se dispara cuando una invoice se anula y Fintoc deshabilita su `hosted_invoice_url`.
`link.created`	`link`	Se dispara cuando Fintoc crea un `Link`.
`link.credentials_changed`	`link`	Se dispara cuando las credenciales de un `Link` cambian y necesitas reconectar el `Link`.
`link.refresh_intent.succeeded`	`refresh_intent`	Se dispara cuando Fintoc termina de actualizar un `Link`. Fintoc envía este evento solo para facturas electrónicas.
`link.refresh_intent.failed`	`refresh_intent`	Se dispara cuando Fintoc no puede terminar de actualizar un `Link`. Fintoc envía este evento solo para facturas electrónicas.
`payment_intent.succeeded`	`payment_intent`	Se dispara cuando un `PaymentIntent` finaliza exitosamente.
`payment_intent.rejected`	`payment_intent`	Se dispara cuando un cliente rechaza un `PaymentIntent`.
`payment_intent.expired`	`payment_intent`	Se dispara cuando un cliente no completa un `PaymentIntent`.
`payment_intent.failed`	`payment_intent`	Se dispara cuando un `PaymentIntent` falla.
`payment_intent.pending`	`payment_intent`	Se dispara cuando el estado final de un `PaymentIntent` aún no está disponible. Fintoc envía un segundo webhook cuando ese estado se resuelve.
`payment_method.activated`	`payment_method`	Se dispara cuando el banco confirma el mandato y el método de pago queda disponible para cobrar.
`payment_method.canceled`	`payment_method`	Se dispara cuando un método de pago deja de estar disponible para cobrar. Deja de generar cargos contra ese método de pago.
`payout.created`	`payout`	Se dispara cuando Fintoc crea un `Payout` y comienza a procesarlo.
`payout.succeeded`	`payout`	Se dispara cuando Fintoc transfiere un `Payout` a tu cuenta bancaria.
`payout.canceled`	`payout`	Se dispara cuando Fintoc cancela un `Payout`. Fintoc no envía a tu cuenta bancaria un `Payout` cancelado.
`payout.returned`	`payout`	🇲🇽 Se dispara cuando tu banco devuelve un `Payout` previamente exitoso. Fintoc incluye los recursos de ese payout en el siguiente.
`refund.in_progress`	`refund`	Se dispara cuando un `Refund` comienza a procesarse.
`refund.succeeded`	`refund`	Se dispara cuando Fintoc procesa un `Refund` exitosamente.
`refund.failed`	`refund`	Se dispara cuando un `Refund` falla.
`subscription.payment_method_updated`	`subscription`	Se dispara cuando Fintoc asocia un método de pago nuevo a la suscripción a través de una `CheckoutSession` con `flow: setup` o con `PATCH /v2/subscriptions/{id}`. Si el método nuevo es un `pac`, el banco puede seguir activando el mandato, así que revisa `pac.status` en el objeto `PaymentMethod` para confirmar si ya es cobrable.
`subscription.payment_method_update_failed`	`subscription`	Se dispara cuando el banco rechaza la activación de un mandato de método de pago nuevo. La suscripción se queda con el método de pago fallido, sin volver automáticamente al anterior, y las invoices abiertas se pueden cobrar mediante el `hosted_invoice_url` de cada una.
`transfer.outbound.succeeded`	`transfer`	Se dispara cuando una `Transfer` saliente se liquida.
`transfer.outbound.partially_succeeded`	`transfer`	🇨🇱 Se dispara cuando solo una parte de una `Transfer` saliente se liquida.
`transfer.outbound.rejected`	`transfer`	Se dispara cuando el Banco de México o la institución contraparte rechaza una `Transfer` saliente antes de liquidarla.
`transfer.outbound.returned`	`transfer`	🇲🇽 Se dispara cuando el Banco de México o la institución contraparte devuelve una `Transfer` saliente.
`transfer.outbound.failed`	`transfer`	Se dispara cuando una `Transfer` saliente no puede llegar a su cuenta destino por un error durante el procesamiento.
`transfer.outbound.reversed`	`transfer`	🇨🇱 Se dispara cuando una `Transfer` saliente que se había liquidado se reversa.
`transfer.inbound.succeeded`	`transfer`	Se dispara cuando tu cuenta recibe una `Transfer` entrante.
`transfer.inbound.returned`	`transfer`	Se dispara cuando el destinatario devuelve una `Transfer` entrante.
`transfer.inbound.rejected`	`transfer`	🇨🇱 Se dispara cuando una `Transfer` entrante se rechaza antes de llegar a tu cuenta.
`transfer.inbound.reversed`	`transfer`	🇨🇱 Se dispara cuando una `Transfer` entrante que tu cuenta ya recibió se reversa y los fondos salen de tu cuenta.
`transfer.inbound.return_failed`	`transfer`	🇲🇽 Se dispara cuando la devolución que solicitaste para una `Transfer` entrante no puede completarse. La `Transfer` vuelve a `succeeded` y los fondos se quedan en tu cuenta.

Eventos de pago de una invoice

Una invoice llega a paid de dos formas, y los eventos son distintos. Cuando Fintoc cobra la invoice, recibes invoice.payment_succeeded y después invoice.paid. Cuando marcas la invoice como pagada porque tu cliente te pagó fuera de Fintoc, recibes solo invoice.paid. Lee external_payment en el payload para distinguir los dos casos. El valor es false cuando la plata pasó por Fintoc y true cuando no.

Anticipos de invoice

Fintoc envía invoice.upcoming antes de cada ciclo de facturación para que puedas avisarle a tu cliente antes de cobrarle. Contacta a Fintoc para definir con cuántos días de anticipación lo recibes. El payload anticipa una invoice que todavía no existe, así que dos campos se comportan distinto que en el resto de los eventos invoice.*:

La invoice no trae id, porque Fintoc todavía no la creó.
El resource_id del evento lleva la suscripción, no la invoice.

Payload de onboarding de una Entity

Los eventos entity.onboarding.approved y entity.onboarding.rejected llevan una vista acotada del onboarding, no el objeto Onboarding completo. El payload identifica el objeto con object_name en vez de object:

{
  "object_name": "onboarding_process",
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "entity": {
    "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN"
  },
  "status": "approved",
  "submitted_at": "2024-01-22T17:04:10.284Z",
  "reviewed_at": "2024-01-23T09:12:44.007Z"
}

Para leer los datos revisados de cada paso, los documentos o los representantes y accionistas declarados, obtén el onboarding con el id del payload.

​Eventos de pago de una invoice

​Anticipos de invoice

​Payload de onboarding de una Entity

Eventos de pago de una invoice

Anticipos de invoice

Payload de onboarding de una Entity