Overview

Belvo makes it easy to get banking, employment, 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?

Banking aggregation

With our Banking product, you can access the following financial data:

ResourceDetailExamples
AccountsGet information about your customer's bank accounts, including the: account type, name, number, currency, and balance.Account model
TransactionsGet a list of bank transactions with all the metadata, including: transaction amount, type, description, currency, status, and value date.Transaction model
OwnersGet details of an account's owner, including: the full name, email, phone number, and address.Owner model

Employment aggregation

With our Employment product, you can access the following employment data:

ResourceDetailExamples
Employment recordsGet 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
EmploymentsGet a comprehensive view of your user’s current social security contributions and employment history. Available for 🇧🇷 Brazil and 🇨🇴Colombia.- Employments Brazil model

- Employments Colombia model
OwnersGet 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.
Owner model

Fiscal aggregation

With our Fiscal product, you can access the following financial data:

ResourceDetailExamples
InvoicesGet 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 statusGet the current tax compliance status of a person or a business from the tax authority in the country.Tax compliance status model
Tax declarationsGet tax declaration information for your users. At the moment only available for 🇨🇴 DIAN Colombia.Tax declaration model
Tax retentionsGet the details on the tax amount retained on invoices.Tax retentions model
Tax returnsGet 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 statusGet 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

Enrichment

Get in-depth and enriched information about your users, based on their banking or employment information.

ResourceDetailExamples
IncomesGet insights on the income of a user through their bank accounts.Income model
Employment metricsGet insights regarding your users employment historyEmployment metrics model
Recurring expensesGet insights regarding a user's recurring expenses.Recurring expenses model
Risk insightsGet insights on a user's financial stability.Risk insights model

Enrich your own data

Send through your own transaction and account data and let Belvo perform an in-depth analysis for you.

ResourceDetailExamples
CategorizationSend through your transaction data and we'll provide additional data about the transaction, including the category and merchant information.Categorization (EYOD)
Income VerificationSend through your transaction data and we'll provide enriched information for each of your user's income streams.Income Verification (EYOD)
Risk insightsSend through your transaction and account data and we'll provide over 120 data points that you can use in your credit models.Risk insights (EYOD)
Recurring ExpensesSend through your own transaction data and we'll analyze and identify any recurring expenses your user has.Recurring Expenses (EYOD)

How does Belvo work?

Once you implement Belvo, your users can connect their bank, fiscal, or employment institutions to your app in just seconds. After your users connect their accounts, Belvo will asynchronously retrieve the information and notify you using webhooks once the information is retrieved.

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, Belvo asynchronously retrieves the financial data and notifies you when it is available to retrieve. This includes the accounts in their name, the real-time balance, transaction information, invoices, and so on.

Example integration flow

1918

A sample banking flow with Belvo

A standard banking integration flow with Belvo looks like 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. If you need to retrieve data about the link itself, you can use our List all links or Get a link’s details requests.

As soon as the data from the institution is asynchronously retrieved, you can access it directly through the List and Detail methods for the given resource.

Finally, you can delete any data from Belvo by calling the Delete method on the given resource.

🚧

Note: Deleting a link will also delete all the related resource information (such as accounts, transactions, and owners) associated with that link. Additionally, deleting an account will also delete all the transactions related to that account.

HTTP Methods

All our endpoints are associated with an HTTP Method with the following standard:

MethodDefinition
GETAccess data from Belvo.
POSTConnect to the institution to register or retrieve data. Retrieved data can be stored by Belvo so that you can access it in the future.
PATCHResume a previous connection request (POST) to the institution to add a 2FA token.
DELETEDelete data from Belvo.

Error handling

📘

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.