Overview

Belvo makes it easy to get banking, gig, fiscal, and income data in LATAM. On this page, we describe the general flow of using Belvo, the HTTP methods we use, and the error codes you might encounter.

Belvo Integration flow

A sample banking flow with BelvoA sample banking flow with Belvo

A sample banking flow with Belvo

A standard banking integration flow with Belvo looks likes this:

  1. Register a link using the Connect Widget
    Your end user connects to their account using our Connect Widget. After they've successfully connected, you'll receive a Link ID that you'll need to use in order to make further requests about the end user.
  2. Wait for historical webhook event
    As soon as your user connects their account, Belvo retrieves historical data about the user and sends a webhook once the information is loaded. Once you receive the webhook, you can make a GET request to the appropriate endpoint to retrieve the information.
  3. Receive update webhook
    Depending on the recurrent link update frequency you set, Belvo retrieves updated information and sends a webhook indicating new information is available for the link. When you receive the webhook, just send a GET request to the appropriate endpoint.

Data persistence

As soon as you register a link, you will not have to do it again. You can use the link.list and link.detail to access it in the future.

Same for the accounts, transactions and owners. As soon as you have pulled the data from the institution, you can keep accessing it directly from Belvo through the list and detail endpoints.

Finally, you can delete any data from Belvo by calling the destroy endpoint on links, accounts, transactions and owners. Note that deleting a link will also delete all the related accounts, transactions and owners, and deleting an account will also delete all the related transactions

HTTP Methods

All our endpoints are associated with a HTTP Method with the following standard

Method

Definition

GET

Access data from Belvo.

POST

Connect to the institution to register or retrieve data. Retrieved data will be stored by Belvo so that you can access it in the future.

PATCH

Resume a previous connection request (POST) to the institution to add a 2FA token.

DELETE

Delete data from Belvo.

Error handling

Errors are annoying - we know. That's why we have dedicated articles for each error in our DevPortal to help you solve them. Have a look at the pages below, or just search for the error code you are encountering to go straight to the causes as well as solutions.

Error searching in the DevPortalError searching in the DevPortal

Error searching in the DevPortal

Error retry policy

Here is our recommendation in terms of retry on errors:

50x errors

Implement an automated exponential backoff of up to five retries. We recommend that you use a base interval of three seconds with a factor of two. For example, the first retry should be after three seconds, the second retry is after 6 seconds (2*3), the third retry is after 12 seconds (2*6), the fourth retry is after 24 seconds (2*12), and the fifth retry is after 48 seconds (2*24).

40x errors

You should not retry making requests if you get 40x response as this is a client error.

The only exception is the “Too Many Sessions” error, as it means that your end-user is accessing the account from another browser at the same time. In this case, please implement the same retry policy as with 50x errors.

Updated about a month ago


Overview


Belvo makes it easy to get banking, gig, fiscal, and income data in LATAM. On this page, we describe the general flow of using Belvo, the HTTP methods we use, and the error codes you might encounter.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.