Historical update

As soon as your banking recurrent link is created, we asynchronously load the maximum number of transactions allowed by the institution. You will receive a historical_update notification whenever the history of transactions is available for you to access.

{
  "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": "2017-01-03", // First transaction date
    "last_transaction_date": "2020-03-25" // Last transaction date
  }
}

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

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

Where:

• {id} is the link_id you receive in your historical_update notification.

New transactions available

You can receive a new_transactions_available notification whenever new transactions are available for a banking recurrent link.

📘

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.

Once you receive the notification, you can query the Transactions endpoint to pull the details of these new transactions. For example, if you receive the following webhook:

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

You can request more information about the transactions with the following query to the Transactions endpoint using the created_at filter:

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

Where:

• {id} is the link_id you received in the notification.
• {date1} is the date when you previously received a notification, in YYYY-MM-DD format.
• {date2} is the date you received the latest notification, in YYYY-MM-DD format.

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), you will receive a transactions_updated webhook with a list of the transactions that have been updated.

{
  "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 'https://api.belvo.com/api/transactions/?link={link_id&}id__in={transaction_id1},{transaction_id2} \
-u [Secret Key ID]:[Secret Key PASSWORD]

Where:

• {link_id} is the ID of the link you received in the webhook notification.
• {transaction_id1} is one ID of a transaction you received in the webhook.
• {transaction_id2} is another ID of a transaction you received in the webhook.

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 enrichment

❗️

Deprecated

This webhook has been deprecated.

As soon as your banking recurrent link is created, we asynchronously gather the merchant information about the user’s historical checking or credit card transactions. You will receive a historical_enrichment notification once Belvo has additional data about the transactions.

{
    "webhook_id": "0649ee907ca74df7a054ba8b2cb0b178",
    "webhook_type": "TRANSACTIONS",
    "webhook_code": "historical_enrichment",
    "link_id": "8d62b9427df2400ab2cf8cd18ce950f6",
    "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
    "data": {
        "total_transactions": 223 // Total number of transactions enriched with merchant information
    }
}