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_process`	Triggers when an `Entity` passes Know Your Customer review. You can now create accounts for the `Entity`.
`entity.onboarding.rejected`	`onboarding_process`	Triggers when an `Entity` fails Know Your Customer review. Create a new onboarding to retry.
`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 a trimmed view of the onboarding, not the full Onboarding object. The payload identifies the object with object_name instead of 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"
}

To read the reviewed step data, the documents, or the declared representatives and shareholders, get the onboarding with the id from the payload.

​Invoice payment events

​Upcoming invoice previews

​Entity onboarding payload

Invoice payment events

Upcoming invoice previews

Entity onboarding payload