Types of events

Fintoc sends a webhook event whenever a resource in your account changes. Event names follow the pattern resource.event, and the event’s data field carries the affected resource. For the envelope that wraps every event, see the Event object. To build an endpoint that receives events, follow the webhooks guide, which covers signature verification and the retry schedule.

You cannot subscribe to the link.created event with a webhook endpoint. To receive the event, pass your backend URL when you configure the widget.

Fintoc sends the following event types today and adds new ones over time, so ignore any type your integration does not recognize:

Event type	`data.object`	Description
`account.refresh_intent.succeeded`	`refresh_intent`	Triggers when Fintoc updates an `Account` with the latest movements available from the bank.
`account.refresh_intent.failed`	`refresh_intent`	Triggers when Fintoc cannot update the movements of an `Account`. Available only on Refresh On Demand plans.
`account.refresh_intent.rejected`	`refresh_intent`	Triggers when Fintoc cannot update the movements of an `Account` because the `Link` credentials are invalid. Available only on Refresh On Demand plans.
`account.refresh_intent.movements_removed`	No `object` field	Triggers when the bank behind a `Link` deletes movements, carrying `account_id` and `movements_removed` with the ids of the deleted movements. Activate these notifications from your dashboard.
`account.refresh_intent.movements_modified`	No `object` field	Triggers when the bank behind a `Link` modifies movements, carrying `account_id` and `movements_changed` with the full `movement` objects that changed. Activate these notifications from your dashboard.
`account_number.deleted`	`account_number`	🇲🇽 Triggers when an account number is deleted, either at your request or because Fintoc purged it as stale.
`account_verification.succeeded`	`account_verification`	Triggers when Fintoc retrieves the holder information of the target account.
`account_verification.failed`	`account_verification`	Triggers when Fintoc cannot retrieve the holder information of the target account.
`checkout_session.finished`	`checkout_session`	Triggers when a customer completes the payment flow. The payload carries the `CheckoutSession`, including the final status of the payment.
`checkout_session.expired`	`checkout_session`	Triggers when a customer leaves the payment flow before finishing.
`dispute.waiting_documentation`	`dispute`	Triggers when your customer contests a card payment with their issuer. Submit your evidence before `documentation_upload_deadline`, or you lose the dispute by default.
`dispute.in_review`	`dispute`	Triggers when you submit the dispute for review and the issuer starts evaluating your evidence.
`dispute.won`	`dispute`	Triggers when the issuer resolves the dispute in your favor and the funds stay with you.
`dispute.lost`	`dispute`	Triggers when the issuer resolves the dispute in your customer’s favor and the funds return to them.
`dispute.expired`	`dispute`	Triggers when `documentation_upload_deadline` passes with no evidence submitted. You lose the dispute.
`entity.onboarding.approved`	`onboarding`	Triggers when an `Entity` passes Know Your Customer review. Fintoc creates the `Entity`’s main `Account`, and you can now create more `Account` objects for the `Entity`.
`entity.onboarding.rejected`	`onboarding`	Triggers when an `Entity` fails Know Your Customer review. What you can do next depends on the onboarding `type`. See Retry after a rejection.
`invoice.created`	`invoice`	Triggers when Fintoc creates an invoice.
`invoice.finalized`	`invoice`	Triggers when Fintoc finalizes an invoice and the invoice becomes ready to pay.
`invoice.paid`	`invoice`	Triggers on every transition to `paid`, whether Fintoc collected the invoice or you marked it as paid outside Fintoc.
`invoice.payment_created`	`invoice`	Triggers when a payment for an invoice starts, either from an automatic charge or from your customer using the `hosted_invoice_url`.
`invoice.payment_succeeded`	`invoice`	Triggers when an invoice payment attempt succeeds.
`invoice.payment_failed`	`invoice`	Triggers when an invoice payment attempt fails.
`invoice.upcoming`	`invoice`	Triggers before a subscription’s next billing cycle, as a preview of the invoice Fintoc is about to create. See Upcoming invoice previews.
`invoice.voided`	`invoice`	Triggers when an invoice becomes void and Fintoc disables its `hosted_invoice_url`.
`link.created`	`link`	Triggers when Fintoc creates a `Link`.
`link.credentials_changed`	`link`	Triggers when the credentials of a `Link` change and you need to reconnect the `Link`.
`link.refresh_intent.succeeded`	`refresh_intent`	Triggers when Fintoc finishes updating a `Link`. Fintoc sends this event only for electronic invoices.
`link.refresh_intent.failed`	`refresh_intent`	Triggers when Fintoc cannot finish updating a `Link`. Fintoc sends this event only for electronic invoices.
`payment_intent.succeeded`	`payment_intent`	Triggers when a `PaymentIntent` finishes successfully.
`payment_intent.rejected`	`payment_intent`	Triggers when a customer rejects a `PaymentIntent`.
`payment_intent.expired`	`payment_intent`	Triggers when a customer does not complete a `PaymentIntent`.
`payment_intent.failed`	`payment_intent`	Triggers when a `PaymentIntent` fails.
`payment_intent.pending`	`payment_intent`	Triggers when the final status of a `PaymentIntent` is not available yet. Fintoc sends a second webhook once that status resolves.
`payment_method.activated`	`payment_method`	Triggers when the bank confirms the mandate and the payment method becomes chargeable.
`payment_method.canceled`	`payment_method`	Triggers when a payment method stops being chargeable. Stop creating charges against that payment method.
`payout.created`	`payout`	Triggers when Fintoc creates a `Payout` and starts processing it.
`payout.succeeded`	`payout`	Triggers when Fintoc transfers a `Payout` to your bank account.
`payout.canceled`	`payout`	Triggers when Fintoc cancels a `Payout`. Fintoc does not send a canceled `Payout` to your bank account.
`payout.returned`	`payout`	🇲🇽 Triggers when your bank returns a previously successful `Payout`. Fintoc includes the resources from that payout in the next one.
`refund.in_progress`	`refund`	Triggers when a `Refund` starts processing.
`refund.succeeded`	`refund`	Triggers when Fintoc processes a `Refund` successfully.
`refund.failed`	`refund`	Triggers when a `Refund` fails.
`subscription.payment_method_updated`	`subscription`	Triggers when Fintoc attaches a new payment method to the subscription through a `CheckoutSession` with `flow: setup` or with `PATCH /v2/subscriptions/{id}`. For a new `pac`, the bank may still be activating the mandate, so check the payment method’s `pac.status` to confirm it is chargeable.
`subscription.payment_method_update_failed`	`subscription`	Triggers when the bank rejects activation of a new payment method mandate. The subscription keeps the failed payment method with no automatic rollback, and your open invoices stay collectible through their `hosted_invoice_url`.
`transfer.outbound.succeeded`	`transfer`	Triggers when an outbound `Transfer` settles.
`transfer.outbound.partially_succeeded`	`transfer`	🇨🇱 Triggers when only part of an outbound `Transfer` settles.
`transfer.outbound.rejected`	`transfer`	Triggers when Banco de México or the counterparty institution rejects an outbound `Transfer` before settlement.
`transfer.outbound.returned`	`transfer`	🇲🇽 Triggers when Banco de México or the counterparty institution returns an outbound `Transfer`.
`transfer.outbound.failed`	`transfer`	Triggers when an outbound `Transfer` cannot reach its destination account because of an error during processing.
`transfer.outbound.reversed`	`transfer`	🇨🇱 Triggers when an outbound `Transfer` that settled is reversed.
`transfer.inbound.succeeded`	`transfer`	Triggers when your account receives an inbound `Transfer`.
`transfer.inbound.returned`	`transfer`	Triggers when the recipient returns an inbound `Transfer`.
`transfer.inbound.rejected`	`transfer`	🇨🇱 Triggers when an inbound `Transfer` is rejected before reaching your account.
`transfer.inbound.reversed`	`transfer`	🇨🇱 Triggers when an inbound `Transfer` your account already received is reversed and the funds leave your account.
`transfer.inbound.return_failed`	`transfer`	🇲🇽 Triggers when a return you requested for an inbound `Transfer` cannot be completed. The `Transfer` goes back to `succeeded` and the funds stay in your account.

Invoice payment events

An invoice reaches paid in two ways, and the events differ. When Fintoc collects the invoice, you receive invoice.payment_succeeded and then invoice.paid. When you mark the invoice as paid because your customer paid you outside Fintoc, you receive invoice.paid alone. Read external_payment in the payload to tell the two apart. The value is false when the money went through Fintoc and true when it did not.

Upcoming invoice previews

Fintoc sends invoice.upcoming ahead of each billing cycle so you can notify your customer before you charge them. Contact Fintoc to set how many days of notice you receive. The payload previews an invoice that does not exist yet, so two fields behave differently from every other invoice.* event:

The invoice carries no id, because Fintoc has not created it.
The event’s resource_id holds the subscription, not the invoice.

Entity onboarding payload

The entity.onboarding.approved and entity.onboarding.rejected events carry the full Onboarding object, so you can read the reviewed step data in data, the uploaded documents, and the declared legal_representatives and shareholders without calling the API again. The payload omits submittable, because a reviewed onboarding can no longer be submitted. For backward compatibility, the payload also keeps two fields that the Onboarding object does not have:

object_name: Always onboarding_process.
entity: A summary of the Entity with its id, holder_id, holder_name, and nationality.

Read type to tell the two kinds of onboarding apart. The keys inside data, and the slots in documents, depend on type and on the Entity’s country.

Account holder

An approved account_holder onboarding lets the Entity own Account objects at Fintoc. The example shows an approved Mexican account_holder onboarding:

{
  "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"
    }
  ]
}

The example is abridged: it shows one entry per array. See the Onboarding object for every field in data, legal_representatives, shareholders, and documents.

Settlement recipient

A settlement_recipient onboarding lets the Entity receive split payments. data.company_information.settlement_account holds the bank account where Fintoc pays the Entity’s share. A Chilean settlement_recipient onboarding opens no document slots, so documents and each legal representative’s documents are empty. The example shows an approved Chilean settlement_recipient onboarding for a company:

{
  "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": []
}

For an Entity that onboards as a natural person, Fintoc ignores legal_representatives, transactional_profile, and shareholders. The payload carries empty legal_representatives and shareholders arrays, and data holds only company_information.

Retry after a rejection

What you can do after entity.onboarding.rejected depends on the onboarding type:

account_holder: You cannot retry through the API. An Entity holds one account_holder onboarding per mode, so creating another one returns 409 Conflict with the code conflicted_request, even after a rejection. Contact Fintoc support to review the case. Fintoc can review a rejected onboarding again and approve it. You then receive entity.onboarding.approved with the same onboarding id, so let your handler accept an approval that arrives after a rejection.
settlement_recipient: Create a new onboarding for the same Entity with the corrected data. A rejected or approved onboarding does not block a new one. While another settlement_recipient onboarding for the Entity is still pending, in_progress, or submitted, creating a new one returns 409 Conflict.

​Invoice payment events

​Upcoming invoice previews

​Entity onboarding payload

​Account holder

​Settlement recipient

​Retry after a rejection

Invoice payment events

Upcoming invoice previews

Entity onboarding payload

Account holder

Settlement recipient

Retry after a rejection