Wait for the results using a Webhook Endpoint

When you request a Refresh Intent, the update isn't immediate. Fintoc first needs to go to the bank to search for new movements and the time that can take depends on the bank and its conection status, but it normally takes between 1 and 3 minutes. So you don't need to ask if the update is finished every 5 seconds, you should create a Webhook Endpoint, where we will notify you through an Event when the Refresh Intent has been completed.

For each account in your Link, we will send you an event. For example, if your Link has three accounts, you will receive three events, each one containing the result of each account update. Keep in mind that the three results could be different, and the Refresh Intent will be marked successful only if every account gets successfully updated.

If everything goes right

If the update goes according to planned when refreshing an account, we will send you an account.refresh_intent.succeeded event that looks like this:

{
  "id": "evt_00000000",
  "type": "account.refresh_intent.succeeded",
  "mode": "live",
  "created_at": "2021-12-07T21:43:54.343Z",
  "data": {
    "object": "refresh_intent",
    "refreshed_object": "account",
    "refreshed_object_id": "acc_00000000",
    "status": "succeeded",
    "created_at": "2021-12-03T00:00:00.000Z",
    "type": "only_last",
    "new_movements": 5
  },
  "object": "event"
}

Inside the data key, you will find the detail about the refresh. In this case, the account with id: acc_00000000 got successfully updated, as its status is succeeded. The new_movements field indicates how many new movements were found during the update. If this number is different to zero, you should query the List Movements endpoint to obtain the new movements. If that number is zero, you can assume that you have the latest movements already.

📘

On demand, recurrent and the new_movements field

The new_movements field refers to the amount of movements new after the update, and not since you last called the API, so you must be careful if your account also has recurrent updates, as the new_movements of a refresh may not be the amount of new movements since you last requested movements to Fintoc.

If something goes wrong

If the update fails, for example if the bank application is down, we will send you an account.refresh_intent.failed event.

{
  "id": "evt_00000000",
  "type": "account.refresh_intent.failed",
  "mode": "test",
  "created_at": "2021-12-07T21:56:07.711Z",
  "data": {
    "object": "refresh_intent",
    "refreshed_object": "account",
    "refreshed_object_id": "acc_00000001",
    "status": "failed",
    "created_at": "2021-12-07T00:00:00.000Z",
    "type": "only_last",
    "new_movements": 0
  },
  "object": "event"
}

Inside the data key, you will find the detail about the refresh. In this case, the account with id: acc_00000000 failed to be updated, as its status is failed. If this is the case, you can create a new Refresh Intent without needing to wait 5 minutes (the time you need to wait between Refresh Intents).

If the credentials are invalid

If the update fails because the credentials are invalid, we will send you an account.refresh_intent.rejected event:

{
  "id": "evt_00000000",
  "type": "account.refresh_intent.rejected",
  "mode": "test",
  "created_at": "2021-12-07T21:56:07.711Z",
  "data": {
    "object": "refresh_intent",
    "refreshed_object": "account",
    "refreshed_object_id": "acc_00000002",
    "status": "rejected",
    "created_at": "2021-12-07T00:00:00.000Z",
    "type": "only_last",
    "new_movements": 0
  },
  "object": "event"
}

Inside the data key, you will find the detail about the refresh. In this case, the account with id: acc_00000000 failed to be updated due to the bank rejecting the credentials as invalid, as its status is rejected. If this is the case, you can create a new Refresh Intent without needing to wait 5 minutes (the time you need to wait between Refresh Intents). But beware. Doing this too many times too fast could lock the user out of its account. We recommend waiting some time between retries.

📘

Invalid credentials

Sometimes, banks say a set of credentials are invalid when they are not. That's why we allow you to retry the Refresh Intent after a rejected status. If the credentials are in fact invalid, you should re-connect the Link through the widget.