Transactions (Webhooks)
Reference information for our Transactions webhook events.
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 thelink_id
you receive in yourhistorical_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 thelink_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
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
}
}
Updated 4 months ago