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`	Se dispara cuando una `Entity` aprueba la revisión de Know Your Customer. Fintoc crea la `Account` principal de la `Entity` y ya puedes crear más objetos `Account` para esa `Entity`.
`entity.onboarding.rejected`	`onboarding`	Se dispara cuando una `Entity` no aprueba la revisión de Know Your Customer. Lo que puedes hacer después depende del `type` del onboarding. Revisa Reintentar tras un rechazo.
`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 el objeto Onboarding completo, así que puedes leer los datos revisados de cada paso en data, los documents subidos y los legal_representatives y shareholders declarados sin volver a llamar a la API. El payload omite submittable, porque un onboarding ya revisado no se puede volver a enviar. Por compatibilidad hacia atrás, el payload también mantiene dos campos que el objeto Onboarding no tiene:

object_name: Siempre onboarding_process.
entity: Un resumen de la Entity con su id, holder_id, holder_name y nationality.

Lee type para distinguir los dos tipos de onboarding. Las llaves dentro de data y los slots de documents dependen de type y del país de la Entity.

Account holder

Un onboarding account_holder aprobado permite que la Entity tenga objetos Account en Fintoc. El ejemplo muestra un onboarding account_holder mexicano aprobado:

{
  "object": "onboarding",
  "object_name": "onboarding_process",
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "entity": {
    "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
    "holder_id": "AAA010101AAA",
    "holder_name": "Test Entity 1",
    "nationality": "mx"
  },
  "type": "account_holder",
  "source": "api",
  "status": "approved",
  "submitted_at": "2026-01-15T15:00:00Z",
  "reviewed_at": "2026-01-16T09:00:00Z",
  "data": {
    "company_information": {
      "business_activity": "Servicios financieros",
      "business_address": "Av. Insurgentes 456, CDMX",
      "fiscal_address": "Av. Reforma 123, CDMX",
      "phone": "+521111111111",
      "settlement_account": "646969000000000000"
    },
    "transactional_profile": {
      "monthly_amount_range": "1_500000",
      "monthly_operations_range": "1_15000",
      "resource_origins": ["trusts", "investments"]
    }
  },
  "legal_representatives": [
    {
      "id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_legal_representative",
      "first_name": "Test Customer 1",
      "last_name": "Customer",
      "email": "rep@example.com",
      "nationality": "mx",
      "identification_number": "AAAA010101HDFAAA01",
      "position": "Director General",
      "documents": [
        {
          "id": "onbdoc_5erFzkDoxfDL0c2cLe0Xq4iQ",
          "slot_key": "identification",
          "status": "uploaded",
          "filename": "identification.pdf",
          "uploaded_at": "2026-01-15T14:30:00Z"
        }
      ]
    }
  ],
  "shareholders": [
    {
      "id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_shareholder",
      "type": "natural_person",
      "name": "Test Customer 2",
      "last_name": "Customer",
      "holder_id": "AAAA010101AAA",
      "percentage": 60,
      "parent_id": null,
      "document": {
        "id": "onbdoc_6fsGblEpygEM1d3dMf1Yr5jR",
        "slot_key": "identification",
        "status": "uploaded",
        "filename": "identification.pdf",
        "uploaded_at": "2026-01-15T14:30:00Z"
      }
    }
  ],
  "documents": [
    {
      "id": "onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO",
      "slot_key": "tax_registration_certificate",
      "status": "uploaded",
      "filename": "tax_registration_certificate.pdf",
      "uploaded_at": "2026-01-15T14:30:00Z"
    }
  ]
}

El ejemplo está abreviado: muestra una entrada por arreglo. Revisa el objeto Onboarding para ver todos los campos de data, legal_representatives, shareholders y documents.

Settlement recipient

Un onboarding settlement_recipient permite que la Entity reciba pagos divididos. data.company_information.settlement_account contiene la cuenta bancaria donde Fintoc le paga su parte a la Entity. Un onboarding settlement_recipient chileno no abre slots de documentos, así que documents y los documents de cada representante legal vienen vacíos. El ejemplo muestra un onboarding settlement_recipient chileno aprobado de una empresa:

{
  "object": "onboarding",
  "object_name": "onboarding_process",
  "id": "onbprc_9kQ2mZpLtR4vXnBc7HdJeKfLgMh",
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "entity": {
    "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
    "holder_id": "000000001",
    "holder_name": "Test Merchant 1 SpA",
    "nationality": "cl"
  },
  "type": "settlement_recipient",
  "source": "api",
  "status": "approved",
  "submitted_at": "2026-01-15T15:00:00Z",
  "reviewed_at": "2026-01-16T09:00:00Z",
  "data": {
    "company_information": {
      "activities_start_date": "2018-05-02",
      "business_activity": "Servicios de arquitectura",
      "business_address": "Av. Apoquindo 100, Santiago, Region Metropolitana, 7550000, Chile",
      "phone": "+56 9 1111 1111",
      "settlement_account": {
        "account_number": "123456789",
        "account_type": "checking_account",
        "institution_id": "cl_banco_de_chile"
      }
    }
  },
  "legal_representatives": [
    {
      "id": "onblr_7gtHcmFqzhFN2e4eNg2Zs6kS",
      "object": "onboarding_legal_representative",
      "first_name": "Test",
      "last_name": "Customer 1",
      "email": "jared@piedpiper.com",
      "nationality": "cl",
      "identification_number": "000000002",
      "position": "Representante legal",
      "phone": null,
      "documents": []
    }
  ],
  "shareholders": [],
  "documents": []
}

Para una Entity que hace el onboarding como persona natural, Fintoc ignora legal_representatives, transactional_profile y shareholders. El payload trae los arreglos legal_representatives y shareholders vacíos, y data contiene solo company_information.

Reintentar tras un rechazo

Lo que puedes hacer después de entity.onboarding.rejected depende del type del onboarding:

account_holder: No puedes reintentar con la API. Una Entity tiene un solo onboarding account_holder por modo, así que crear otro devuelve 409 Conflict con el código conflicted_request, incluso después de un rechazo. Contacta al soporte de Fintoc para revisar el caso. Fintoc puede volver a revisar un onboarding rechazado y aprobarlo. En ese caso recibes entity.onboarding.approved con el mismo id de onboarding, así que tu handler debe aceptar una aprobación que llega después de un rechazo.
settlement_recipient: Crea un nuevo onboarding para la misma Entity con los datos corregidos. Un onboarding rejected o approved no bloquea uno nuevo. Mientras otro onboarding settlement_recipient de la Entity siga en pending, in_progress o submitted, crear uno nuevo devuelve 409 Conflict.

​Eventos de pago de una invoice

​Anticipos de invoice

​Payload de onboarding de una Entity

​Account holder

​Settlement recipient

​Reintentar tras un rechazo

Eventos de pago de una invoice

Anticipos de invoice

Payload de onboarding de una Entity

Account holder

Settlement recipient

Reintentar tras un rechazo