Skip to main content
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.
Use the Product column to choose events for the product you are integrating. Some events apply to more than one product.
For Business Accounts transfers, subscribe to transfer.inbound.* or transfer.outbound.*. The checkout_session.*, payment_intent.*, and payout.* events belong to Payments. A Payout settles funds collected through Payments to your bank account; it does not represent an outbound Business Accounts transfer.
Fintoc sends the following event types today and adds new ones over time, so ignore any type your integration does not recognize:

​
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:
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:
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.