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 using the created_at filter:

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

Historical enrichment

📘

Merchant ID BETA Program

This webhook is part of our new Merchant ID BETA program, where we provide additional information about the merchant involved in a transaction. If you would like to join the program, just reach out to our support team.

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",
    "data": {
        "total_transactions": 223 // Total number of transaction enriched with merchant information
    }
}

New transactions enriched

📘

Merchant ID BETA Program

This webhook is part of our new Merchant ID BETA program, where we provide additional information about the merchant involved in a transaction. If you would like to join the program, just reach out to our support team.

You can receive a new_transactions_enriched notification whenever new checking or credit card transactions are available for a banking recurrent link and have been enriched with merchant information.

{
    "webhook_id": "0649ee907ca74df7a054ba8b2cb0b178",
    "webhook_type": "TRANSACTIONS",
    "webhook_code": "new_transactions_enriched",
    "link_id": "8d62b9427df2400ab2cf8cd18ce950f6",
    "data": {
        "new_transactions": 22 // Number of new transactions enriched with merchant information
    }
}

Did this page help you?