Transactions

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",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "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 pull the complete list of transactions for that link using the following call:

curl --request GET 'https://api.belvo.com/api/transactions/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]
client.transaction.list({
  filters: {
    link: "{id}"
  }
})
client.Transaction.list(link="{id}")
client.transaction.list(params: {
  link: "{id}"
})

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 bank 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",
  "webhook_code": "new_transactions_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "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:

curl --request GET 'https://api.belvo.co/api/transactions/?link={id}&collected_at__range={date1},{date2}' \
-u [Secret Key ID]:[Secret Key PASSWORD]
client.transaction.list({
  filters: {
    link: "{id}",
    collected_at__range: "{date1},{date2}"
  }
})
client.Transaction.list(link="{id}",collected_at__range="{date1},{date2}")
client.transaction.list(params: {
  link: "{id}",
  collected_at__range: "{date1},{date2}"
})

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.

Did this page help you?