Historical update

As soon as your banking link is created, we asynchronously load the transactions available for the link and will send you the following webhook:

Webhook Code	Description
historical_update	The total number of transactions for the link for the past year.

In the webhook payload we include the number of transactions found for the link (including the number of inflow and outflow transactions) as well as the date range that the information applies to.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_transactions": 19, // Total number of transactions found
    "total_inflow_transactions": 10, // Total number of inflow transactions
    "total_outflow_transactions": 9, // Total number of outflow transactions
    "first_transaction_date": "2023-01-03", // First transaction date
    "last_transaction_date": "2024-01-03" // Last transaction date
  }
}

Once you receive the notification, you can get further details by making the following request:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/transactions/?link=link_id'

Query Parameter	Description	Example
`link`	The `link_id` you received in the webhook notification.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

You can add further filters to narrow down the results, for example:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/transactions/?link=link_id&type=INFLOW&value_date__range=first_transaction_date,last_transaction_date'

Query Parameter	Description	Example
`link`	The `link_id` you received in the webhook notification.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`type`	The type of transaction. Can be either `INFLOW` or `OUTFLOW`.	`INFLOW`
`value_date__range`	The date range that you want to get transactions for. This should be the `first_transaction_date` and `last_transaction_date` you received in the webhook notification.	`2023-01-03,2024-01-03`

New transactions available

According to your chosen refresh rate, Belvo will asynchronously retrieve data about any new transactions that have appeared for the given link since the last update.

📘
We define new transactions as transactions found in the institution for a given link since the last update. For example, these could be new transactions from the last 24 hours or new transactions from a few days ago that were only just added by the institution.

Webhook Code	Description
`new_transactions_available`	The number of new transactions found in the institution since the last update.

In the webhook payload we include the number of new transactions found for the link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "new_transactions_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_transactions": 19 // Number of new transactions found since last event
  }
}

Once you receive the notification, you can get further details by making the following request:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/transactions/?link=link_id&type=INFLOW&created_at__range=date1,date2'

Query Parameter	Description	Example
`link`	The `link_id` you received in the webhook notification.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`created_at__range`	The date range you want to receive transactions for. We recommend that `date1` is the date when you previously received a notification and `date2` is the date when you receive the current notification (both in `YYYY-MM-DD` format).	`2024-05-01,2024-06-01`

Transaction updated

📘
This webhook is available for both single and recurrent links.

Whenever Belvo identifies that a transaction has been updated in the institution (for example, a change to the description field or the value date), and will send you the following webhook:

Webhook Code	Description
`transactions_updated`	The number of transactions updated along with the list of transaction IDs.

In the webhook payload we include the number of transactions that were updated along with a list of Belvo transaction IDs.

{
  "webhook_id": "28364bef400f4374a80872b61ba204289",
  "webhook_type": "TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "transactions_updated",
  "link_id": "0284557b-df47-450a-po09e-7875195c2259",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "count": 5, // Total number of transactions updated.
    "updated_transactions": [
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17", // The ID of the updated transaction.
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}

Once you receive the notification, you can pull the complete list of transactions for that link using the following call:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/transactions/?link=link_id&id__in=transaction1,transaction2,transaction3

Query Parameter	Description	Example
`link`	The `link_id` you received in the webhook notification.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`id__in`	The list of transaction `id`s you received in the `data.updated_transactions` of the webhook notification.	`7d0afe4c-373d-490c-90e4-06xx4cdd4a17,53759bc-ca02-46f0-b1d5-31xxcd54db41,64ecc7df-f322-4934-82f5-3b3ae675ef4a`

Changes that trigger a `transactions_updated webhook`

Belvo monitors the following fields for all transactions and when it detects a change between the last time it retrieved data and now, it will send you a transactions_updated webhook:

amount
currency
description
value_date
internal_identification
type
status
credit_card_data.bill_internal_identification (OFDA only)
credit_card_data.credit_card_bill.id (OFDA only)

Transaction deleted

📘
This webhook is available for both single and recurrent links.

Belvo regularly monitors and cleans transactional data in its database to improve the consistency of the data you receive. When a transaction is identified to be duplicated (which can occur, for example, due to POST calls made in quick succession to the API for the same link), it is removed from the database. In this case, you will receive a transactions_deleted webhook with a list of the transactions that have been deleted.

{
  "webhook_id": "28364bef400f4374a80872b61ba204289",
  "webhook_type": "TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "transactions_deleted",
  "link_id": "0284557b-df47-450a-po09e-7875195c2259",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "count": 5, // Total number of transactions deleted.
    "deleted_transactions": [
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17", // The ID of the deleted transaction.
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}

Historical update

New transactions available

📘

Transaction updated

📘

Changes that trigger a transactions_updated webhook

Transaction deleted

📘

Changes that trigger a `transactions_updated webhook`