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.

Usa la columna Producto para elegir los eventos del producto que estás integrando. Algunos eventos corresponden a más de un producto.

Para transferencias de Business Accounts, suscríbete a transfer.inbound.* o transfer.outbound.*. Los eventos checkout_session.*, payment_intent.* y payout.* corresponden a Payments. Un Payout liquida los fondos recaudados mediante Payments a tu cuenta bancaria; no representa una transferencia saliente de Business Accounts.

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	Producto	`data.object`	Descripción
`account.refresh_intent.succeeded`	Movements	`refresh_intent`	Se dispara cuando Fintoc actualiza una `Account` con los últimos movimientos disponibles del banco.
`account.refresh_intent.failed`	Movements	`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`	Movements	`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`	Movements	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`	Movements	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`	Business Accounts	`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`	Business Accounts	`account_verification`	Se dispara cuando Fintoc obtiene la información del titular de la cuenta destino.
`account_verification.failed`	Business Accounts	`account_verification`	Se dispara cuando Fintoc no puede obtener la información del titular de la cuenta destino.
`charge.succeeded`	Direct Debit (Legacy)	`charge`	Se dispara cuando el banco confirma que un `Charge` fue exitoso.
`charge.failed`	Direct Debit (Legacy)	`charge`	Se dispara cuando un `Charge` falla, por ejemplo por fondos insuficientes, un monto superior al límite permitido o una autorización deshabilitada.
`checkout_session.finished`	Payments	`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`	Payments	`checkout_session`	Se dispara cuando un cliente abandona el flujo de pago antes de finalizar.
`dispute.waiting_documentation`	Payments	`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`	Payments	`dispute`	Se dispara cuando envías la disputa a revisión y el emisor empieza a evaluar tu evidencia.
`dispute.won`	Payments	`dispute`	Se dispara cuando el emisor resuelve la disputa a tu favor y los fondos se quedan contigo.
`dispute.lost`	Payments	`dispute`	Se dispara cuando el emisor resuelve la disputa a favor de tu cliente y los fondos vuelven a él.
`dispute.expired`	Payments	`dispute`	Se dispara cuando `documentation_upload_deadline` vence sin evidencia enviada. Pierdes la disputa.
`entity.onboarding.approved`	Business Accounts, Payments	`onboarding`	Se dispara cuando una `Entity` aprueba la revisión de Know Your Customer. Un onboarding `account_holder` aprobado crea la `Account` principal de la `Entity`; un onboarding `settlement_recipient` aprobado permite que la `Entity` reciba pagos divididos.
`entity.onboarding.rejected`	Business Accounts, Payments	`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`	Payments	`invoice`	Se dispara cuando Fintoc crea una invoice.
`invoice.finalized`	Payments	`invoice`	Se dispara cuando Fintoc finaliza una invoice y la invoice queda lista para pagarse.
`invoice.paid`	Payments	`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.marked_uncollectible`	Payments	`invoice`	Se dispara cuando una invoice `open` pasa a `uncollectible`, por ejemplo cuando la marcas como incobrable.
`invoice.payment_created`	Payments	`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`	Payments	`invoice`	Se dispara cuando un intento de pago de una invoice resulta exitoso.
`invoice.payment_failed`	Payments	`invoice`	Se dispara cuando falla un intento de pago de una invoice.
`invoice.upcoming`	Payments	`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`	Payments	`invoice`	Se dispara cuando una invoice se anula y Fintoc deshabilita su `hosted_invoice_url`.
`link.created`	Movements, Fiscal	`link`	Se dispara cuando Fintoc crea un `Link`.
`link.credentials_changed`	Movements, Fiscal	`link`	Se dispara cuando las credenciales de un `Link` cambian y necesitas reconectar el `Link`.
`link.refresh_intent.succeeded`	Fiscal	`refresh_intent`	Se dispara cuando Fintoc termina de actualizar documentos tributarios electrónicos o declaraciones mensuales para un `Link` fiscal.
`link.refresh_intent.failed`	Fiscal	`refresh_intent`	Se dispara cuando Fintoc no puede terminar de actualizar documentos tributarios electrónicos para un `Link` fiscal.
`payment_intent.succeeded`	Payments	`payment_intent`	Se dispara cuando un `PaymentIntent` finaliza exitosamente.
`payment_intent.rejected`	Payments	`payment_intent`	Se dispara cuando un cliente rechaza un `PaymentIntent`.
`payment_intent.expired`	Payments	`payment_intent`	Se dispara cuando un cliente no completa un `PaymentIntent`.
`payment_intent.failed`	Payments	`payment_intent`	Se dispara cuando un `PaymentIntent` falla.
`payment_intent.pending`	Payments	`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`	Payments	`payment_method`	Se dispara cuando el banco confirma el mandato y el método de pago queda disponible para cobrar.
`payment_method.canceled`	Payments	`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`	Payments	`payout`	Se dispara cuando Fintoc crea un `Payout` y comienza a procesarlo.
`payout.succeeded`	Payments	`payout`	Se dispara cuando Fintoc transfiere un `Payout` a tu cuenta bancaria.
`payout.canceled`	Payments	`payout`	Se dispara cuando Fintoc cancela un `Payout`. Fintoc no envía a tu cuenta bancaria un `Payout` cancelado.
`payout.returned`	Payments	`payout`	🇲🇽 Se dispara cuando tu banco devuelve un `Payout` previamente exitoso. Fintoc incluye los recursos de ese payout en el siguiente.
`refund.in_progress`	Payments	`refund`	Se dispara cuando un `Refund` comienza a procesarse.
`refund.succeeded`	Payments	`refund`	Se dispara cuando Fintoc procesa un `Refund` exitosamente.
`refund.failed`	Payments	`refund`	Se dispara cuando un `Refund` falla.
`refund.returned`	Payments	`refund`	Se dispara cuando el banco del destinatario devuelve la transferencia de un `Refund` en `succeeded`.
`subscription.payment_method_updated`	Payments	`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`	Payments	`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.
`subscription_intent.succeeded`	Direct Debit (Legacy)	`subscription_intent`	Se dispara cuando un `SubscriptionIntent` es exitoso y la cuenta de tu cliente queda inscrita.
`subscription_intent.failed`	Direct Debit (Legacy)	`subscription_intent`	Se dispara cuando un `SubscriptionIntent` falla por un error del banco o de Fintoc.
`subscription_intent.rejected`	Direct Debit (Legacy)	`subscription_intent`	Se dispara cuando tu cliente rechaza un `SubscriptionIntent`, incluido un segundo factor fallido.
`transfer.outbound.succeeded`	Business Accounts	`transfer`	Se dispara cuando una `Transfer` saliente se liquida.
`transfer.outbound.partially_succeeded`	Business Accounts	`transfer`	🇨🇱 Se dispara cuando solo una parte de una `Transfer` saliente se liquida.
`transfer.outbound.returned`	Business Accounts	`transfer`	🇲🇽 Se dispara cuando el Banco de México o la institución contraparte devuelve una `Transfer` saliente.
`transfer.outbound.failed`	Business Accounts	`transfer`	Se dispara cuando una `Transfer` saliente no puede llegar a su cuenta destino por un error de procesamiento o porque el Banco de México o la institución contraparte rechaza la transferencia antes de liquidarla.
`transfer.outbound.reversed`	Business Accounts	`transfer`	🇨🇱 Se dispara cuando una `Transfer` saliente que se había liquidado se reversa.
`transfer.inbound.succeeded`	Business Accounts	`transfer`	Se dispara cuando tu cuenta recibe una `Transfer` entrante.
`transfer.inbound.returned`	Business Accounts	`transfer`	Se dispara cuando el destinatario devuelve una `Transfer` entrante.
`transfer.inbound.rejected`	Business Accounts	`transfer`	🇨🇱 Se dispara cuando una `Transfer` entrante se rechaza antes de llegar a tu cuenta.
`transfer.inbound.reversed`	Business Accounts	`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`	Business Accounts	`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.
`transfer_batch.in_progress`	Business Accounts	`transfer_batch`	Se dispara cuando apruebas un `TransferBatch` desde el Dashboard y Fintoc empieza a enviar sus transferencias.
`transfer_batch.rejected`	Business Accounts	`transfer_batch`	Se dispara cuando rechazas un `TransferBatch` desde el Dashboard. Fintoc no envía ninguna de sus transferencias.
`transfer_batch.expired`	Business Accounts	`transfer_batch`	Se dispara cuando nadie aprueba un `TransferBatch` en dos semanas. Fintoc no envía ninguna de sus transferencias.
`transfer_batch.succeeded`	Business Accounts	`transfer_batch`	Se dispara cuando todas las transferencias de un `TransferBatch` son exitosas.
`transfer_batch.partially_succeeded`	Business Accounts	`transfer_batch`	Se dispara cuando un `TransferBatch` termina con algunas transferencias exitosas y otras fallidas.
`transfer_batch.failed`	Business Accounts	`transfer_batch`	Se dispara cuando un `TransferBatch` termina sin transferencias exitosas.

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.

API de Fintoc

Recursos principales

API de Pagos

API de Business Accounts

API de Movimientos

Direct Debit (Legacy)

API Fiscal

Tipos de eventos

Eventos de pago de una invoice

Anticipos de invoice

Payload de onboarding de una Entity

Account holder

Settlement recipient

Reintentar tras un rechazo

API de Fintoc

Recursos principales

API de Pagos

API de Business Accounts

API de Movimientos

Direct Debit (Legacy)

API Fiscal

​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