Belvo makes it easy to get banking, 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.
What is Belvo's aggregation and enrichment solution?
Our solution for Latin America allows companies to securely access financial information through our banking, employment, and fiscal products.
What information can I access?
With our Banking product, you can access the following financial data:
|Accounts||Get information about your customer's bank accounts, including the: account type, name, number, currency, and balance.||Account model|
|Transactions||Get a list of bank transactions with all the metadata, including: transaction amount, type, description, currency, status, and value date.||Transaction model|
|Owners||Get details of an account's owner, including: the full name, email, phone number, and address.||Owner model|
|Balances||Get the current or historical balance of your customer's bank accounts.||Balance model|
With our Employment product, you can access the following employment data:
|Employment records||Get a comprehensive view of your user’s current social security contributions and employment history. At the moment only available for 🇲🇽 IMSS Mexico.||Employment records model|
|Owners||Get personal details about the user, including their full name, email, and ID document information.|
Note: This is the same resource as for our Banking aggregation product.
With our Fiscal product, you can access the following financial data:
|Invoices||Get details on all certified invoices sent and received by a business or a person, including: the sender's and receiver's name, the invoice type, amount, currency, and much more!||Invoice model|
|Tax compliance status||Get the current tax compliance status of a person or a business from the tax authority in the country.||Tax compliance status model|
|Tax declarations||Get tax declaration information for your users. At the moment only available for 🇨🇴 DIAN Colombia.||Tax declaration model|
|Tax retentions||Get the details on the tax amount retained on invoices.||Tax retentions model|
|Tax returns||Get all the information about the monthly or yearly tax returns sent to the tax authority by a person or a business. At the moment only available for 🇲🇽 SAT Mexico.||Tax return model|
|Tax status||Get details on the tax situation of a person or a business on the tax authority in the country, including their: name, address, tax ID, and economic activity.||Tax status model|
Get in-depth and enriched information about your users, based on their banking information.
|Incomes||Get insights on the income of a user through their bank accounts.||Income model|
|Recurring expenses||Get insights regarding a user's recurring expenses.||Recurring expenses model|
|Risk insights||Get insights on a user's financial stability.||Risk insights model|
|Categorization||Send through your transaction data and we'll provide additional data about the transaction, including the category and merchant information.||Categorization model|
|Income Verification||Send through your transaction data and we'll provide enriched information for each of your user's income streams.||Income Verification model|
How does Belvo work?
Once you implement Belvo, your users can connect their bank or tax accounts to your app in just seconds. After which, you can retrieve financial information about that user.
To create this connection, your users need to share their online credentials with Belvo. We encrypt these credentials as we receive them and only use them to access the account in read-only mode.
Once the Link is created between your app and your user's institution account, you can pull financial data. This includes the accounts in their name, the real-time balance, transaction information, invoices, and so on.
Belvo Integration flow
A standard banking integration flow with Belvo looks like this:
- 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.
- 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.
- 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.
As soon as you register a link, you will not have to do it again. You can use the
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
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, while deleting an account will also delete all the related transactions
All our endpoints are associated with an HTTP Method with the following standard:
|Access data from Belvo.|
|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.|
|Resume a previous connection request (POST) to the institution to add a 2FA token.|
|Delete data from Belvo.|
Save the request_id!
Make sure that when you receive an error you log the
request_id. This will allow Belvo to debug the issue more swiftly and get back up and running as quickly as possible.
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 our API and Widget errors page, or just search for the error code you are encountering to go straight to the causes as well as solutions.
Updated 21 days ago