Connect to all finance institutions in Latin America

Welcome to Belvo's API

Belvo is an open banking and fiscal API for Latin America helping innovative companies to access banking and fiscal information in a secure and agile way.

To get up and running right away, follow our quick start guide.


Get started › Create account ›

Build with Belvo API

📘

In this section, you will have access to more advanced topics like error handling, 2FA management and financial data lifecycle.

In the previous section, we covered the basic steps to register a new link and to retrieve accounts and transactions information from the link.

In this section, we will cover more advanced topics that will allow us to use the full potential of Belvo products.

Belvo products

Belvo currently offer 3 products with different type of financial information for developers:

  • Banking with information like account statements, real time balance, historical transactions and account owner identification
  • Fiscal with information like received and sent invoices and tax returns
  • Gig economy with information like trips and full details on the gig driver

All our products share the same core resources to work: institutions and links.

Core resources

Institutions

An Institution is an entity that Belvo can access information from. It can be:

  • a bank institution like Banamex retail banking or HSBC business banking
  • a fiscal institution such as the "Servicio de Administración Tributaria" (SAT) in Mexico
  • a gig institution such as Uber or Rappi

Endpoint

Method

Description

List

GET

List of all institutions currently supported by Belvo.

Links

A Link is a set of credentials associated to a end-user access to an Institution. An example would be the username and password used to login to an online banking platform. You will need to register a Link before accessing information from that specific end-user like Account information or Transaction details.

Endpoint

Method

Description

Register

POST

Register a new link from a financial institution to your Belvo account.

List

GET

List of all links currently associated with your Belvo account.

Resume

PATCH

Resume a link registering session that was paused because a MFA token was required by the institution.

Detail

GET

Get the details of a specific link.

Update

PUT

Update the password of a specific link.

Destroy

DELETE

Delete permanently a link and all associated accounts, transactions and owners information from your Belvo account.

Difference between single and recurrent link

Using Belvo Open Banking API, you have the possibility to register two types of links:

Single links

Single links are used to perform ad hoc data access to accounts, owners and transactions.
For single links you will have to perform POST calls to retrieve accounts, owners and transactions every time you want to access fresh data from the institution.

Recurrent links

With recurrent links, Belvo refresh automatically information on a daily basis so you always have up to date data.

As soon as a recurrent link is created, we load automatically and asynchronously the full history of data in the link:

  • For bank institutions:
    • we load all accounts, past transactions and ownership information in the link
    • we notify you via webhook events as soon as the historical data is loaded and available for you to use
  • For fiscal institutions:
    • we load all invoices, tax returns and tax status in the link
    • we notify you via webhook events as soon as the historical data is loaded and available for you to use

In addition to this initial historical loading, every day, we connect to the institution to retrieve:

  • For bank institutions:
    • the accounts information of the link, including the live balance and credit data
    • the new transactions added during the last 365 days
    • the owners personal information of the link
  • For fiscal institutions:
    • the new invoices sent or received during the last 5 years
    • the new tax return added in the last 5 years

Then, as soon as you need the data, you can directly use the list/detail endpoints to instantly access up to date information, without needing to connect to the institution.

👍

Important information regarding recurrent links

  • they are refreshed every day at 14.30 UTC
  • custom encryption_key cannot be used for recurrent links, our own secret must be used to encrypt the link
  • links from our Gig economy product are not supported as recurrent links yet

The life of a link

A link can have different status. The link status is used to reflect if the link is operational or if an action is needed to restore the link.

Status

Description

valid

A valid link is a fully working link.

invalid

An invalid link means that the credentials are no longer valid. It requires a credentials update from the user to be valid again.
⇒ You can use the Connect widget in update mode to ask your user to provide a new password.

unconfirmed

An unconfirmed link means that the link was never created successfully, a token was needed and never provided by the user. You need to resume the link creation process with a token to complete the link creation.

token_required

A token_required link means that a previously valid link now requires a new token. You need to resume the link update process with a token.
⇒ You can use the Connect widget in update mode to ask your user to provide a fresh MFA token.

Checking the status of a link

You can find the status of a link by checking the link listing or link details.

curl https://api.belvo.co/api/links/c70a25d4-d8ad-9999-b59e-b8f57f0e7123 \
  -u [Secret Key ID]:[Secret Key PASSWORD]
{
    “id”: “c70a25d4-d8ad-9999-b59e-b8f57f0e7123",
    “institution”: “liverpool_mx_retail”,
    “access_mode”: “single”,
    “last_accessed_at”: “2019-10-04T10:58:20.374432Z”,
    “status”: “valid”,
    “created_by”: “b18626ab-74aa-45fd-a66d-babf1461f962"
}

Banking

Our Banking product is offering different resources to give access to a comprehensive list of bank information.

Accounts

📘

The account resource is only available for the links created with institutions of type bank or gig.

An Account is the representation of a bank account inside a financial institution. An end-user can have several Accounts inside each Link. For example, one Link can have one checking account, several credit cards and even loan or investment accounts.

Endpoints

Method

Description

Retrieve

POST

Retrieve all accounts related to a specific link.

List

GET

List all the accounts from all the Links already associated with your Belvo account.

Resume

PATCH

Resume an account retrieving session that was paused because a MFA token was required by the institution.

Detail

GET

Get the details of a specific account.

Destroy

DELETE

Delete permanently an account and all associated transactions from your Belvo account.

Transactions

📘

The transaction resource is only available for the links created with institutions of type bank or gig.

A Transaction contains the detailed information of each movement inside an Account.

Endpoints

Method

Description

Retrieve

POST

Retrieve all transactions related to a specific account within a specified data range.

List

GET

List all transactions already associated with your Belvo account.

Resume

PATCH

Resume a transaction retrieving session that was paused because a MFA token was required by the institution.

Detail

GET

Get the details of a specific transaction.

Destroy

DELETE

Delete permanently a transaction from your Belvo account.

Transaction categorization BETA

Using a combination of internal and external data sources, Belvo is able to provide a clean and standardised category for most of transactions.
A category is automatically assigned to each transaction as soon it is retrieved from the bank.

Here is the list of categories we support:

Category

Example of transaction

Deposits

"DEPOSITO INTERBANCARIO"

Home & Life

"ELEKTRA MEXIC"

Food & Groceries

"OXXO CIPRESES"

Online Platforms & Leisure

"NETFLIX COM CR"

Transport & Travel

"UBER TRIP HELP.UBER.COM"

Personal Shopping

"LIVERPOOL POR INTERNET"

Taxes

"IVA COM MEMBRESIA"

Withdrawal & ATM

"RETIRO CAJERO AUTOMATICO"

Credits & Loans

"ABONO A CREDITO GLOBAL"

Bills & Utilities

"HT TELCEL 018008"

Investments & Savings

"ABONO INTERESES AHORROS"

Fees & Charges

"COMISION EMISION"

Income & Payments

"PAGO DE NOMINA"

Transfers

"SPEI RECIBIDOSTP"

👍

BETA program

BETA: Feel free to contact us at [email protected] if you'd like to test our transaction categorization.

Balances

📘

The balance resource is only available for the links created with institutions of type bank.

A Balance represents the financial status of an Account at a given time.

Endpoints

Method

Description

Retrieve

POST

Retrieve balances from a specific account or all accounts from a specific link. You can retrieve the balances at the end of the day for all accounts between two dates.

List

GET

List all existing balances in your Belvo account.

Resume

PATCH

Resume a Balance retrieve session that was paused because a MFA token was required by the institution.

Detail

GET

Get the details of a specific balance.

Destroy

DELETE

Delete a specific balance from your Belvo account.

Incomes BETA

📘

The income resource is only available for the links created with institutions of type bank.

An Income represents a list of insights about the income of a user through its bank Accounts.

The Income insights resource is currently in BETA version.
Contact us at [email protected] if you want to be part of this BETA.

Endpoints

Method

Description

Retrieve

POST

Retrieve income insights from a specific link.
The period is up to 365 days and depends on the transaction history available for each bank.

Owners

📘

The owner resource is only available for the links created with institutions of type bank.

An Owner represents the person who has access to a Link and is the owner of all the Accounts inside the Link

Endpoints

Method

Description

Retrieve

POST

Retrieve the owner detail of a specific link.

List

GET

List all owners associated to your Belvo account.

Resume

PATCH

Resume a owner retrieving session that was paused because a MFA token was required by the institution.

Detail

GET

Get the details of a specific owner.

Destroy

DELETE

Delete permanently a owner from your Belvo account.

Fiscal

Our Fiscal product is offering different resources to give access to a comprehensive list of tax information.

Invoices

📘

The invoice resource is only available for the links created with institutions of type fiscal.

An Invoice is the representation of an electronic invoice, that can be received or sent, by a business or an individual and has been uploaded to the fiscal institution website. Multiple INFLOW (invoice received) and OUTFLOW (invoice sent) invoices can be retrieved inside each link coming from a fiscal institution.

Endpoints

Method

Description

Retrieve

POST

Retrieve invoices information from a specific fiscal link.

List

GET

List of all existing invoices in your Belvo account.

Detail

GET

Get the details of a specific invoice.

Destroy

DELETE

Delete permanently a specific invoice from your Belvo account.

Tax returns

📘

The tax return resource is only available for the links created with institutions of type fiscal.

A Tax return is the representation of the tax return document sent every year by a person or a business to the tax authority in the country.

The tax return data structure will be different depending on if it is related to a person or a business (you will find examples for both in the API reference).

Endpoints

Method

Description

Retrieve

POST

Retrieve tax return information from a specific fiscal link.

List

GET

List of all existing tax returns in your Belvo account.

Detail

GET

Get the details of a specific tax return.

Destroy

DELETE

Delete permanently a specific tax return from your Belvo account.

Tax status

A Tax status - Constancia de situación fiscal - is the representation of the tax situation of a person or a business on the tax authority in the country.

📘

The tax status resource is only available for the links created with institutions of type fiscal.

The tax status data structure will be different depending on if it is related to a person or a business.

Endpoints

Method

Description

Retrieve

POST

Retrieve tax status information from a specific fiscal link.

List

GET

List of all existing tax status in your Belvo account.

Detail

GET

Get the details of a specific tax status.

Destroy

DELETE

Delete permanently a specific tax status from your Belvo account.

Gig economy

Our Gig economy product is offering different resources to give access to a comprehensive list of gig information.

Accounts

An Account is the representation of a gig account inside a gig economy application. An end-user usually has one Accounts inside each Link.

Endpoints

Method

Description

Retrieve

POST

Retrieve all accounts related to a specific link.

List

GET

List all the accounts from all the Links already associated with your Belvo account.

Resume

PATCH

Resume an account retrieving session that was paused because a MFA token was required by the institution.

Detail

GET

Get the details of a specific account.

Destroy

DELETE

Delete permanently an account and all associated transactions from your Belvo account.

Transactions

A Transaction contains the detailed information of each movement inside an Account.

Endpoints

Method

Description

Retrieve

POST

Retrieve all transactions related to a specific link.

List

GET

List all the transactions from all the Links already associated with your Belvo account.

Resume

PATCH

Resume a transactions retrieving session that was paused because a MFA token was required by the institution.

Detail

GET

Get the details of a specific transaction.

Destroy

DELETE

Delete permanently a transaction from your Belvo account.

Owners

An Owner represents the person who has access to a Link and is the owner of all the Accounts inside the Link

Endpoints

Method

Description

Retrieve

POST

Retrieve all owners related to a specific link.

List

GET

List all the owners from all the Links already associated with your Belvo account.

Resume

PATCH

Resume an owner retrieving session that was paused because a MFA token was required by the institution.

Detail

GET

Get the details of a specific owner.

Destroy

DELETE

Delete permanently an owner from your Belvo account.

Balances

A Balance represents the financial status of an Account at a given time.

Endpoints

Method

Description

Retrieve

POST

Retrieve all balances related to a specific link.

List

GET

List all the balances from all the Links already associated with your Belvo account.

Resume

PATCH

Resume a balance retrieving session that was paused because a MFA token was required by the institution.

Detail

GET

Get the details of a specific balance.

Destroy

DELETE

Delete permanently a balance from your Belvo account.

Integration overview

HTTP Methods

All our endpoints are associated to 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.

Belvo Integration flow

In this section, we will walk you through a standard Belvo integration flow:

  • Register a link: You always have to start by creating a link between your application and an institution. Once the link is created, we will share a link id that you can use to access the account.
  • Retrieve accounts: using the previously created link, you can retrieve the accounts within this link. Once the accounts are retrieved, you will get an account id along with meta data and real time balance for each account.
  • Retrieve transactions: using the previously created accounts, you can pull a list of detailed transactions for each account within a specified data range.
  • Delete the link: you can delete the link from Belvo and it will delete all stored data related to it: accounts, transactions, link, ...

Here is an example of flow to access accounts and transactions, before deleting the link:

Data persistance

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

Environment

Belvo is currently offering two environments.
To generate your keys for each environment, have a look to our guide to get your Belvo API keys.

Environment

Purpose

Base URL

Sandbox

The sandbox environment is dedicated to test and development phases.
In this environment, you can create links without real credentials and you can pull test data from all endpoints.
⚠️ Gig links cannot be created and tested in Sandbox.
⚠️ The sandbox environment is refreshed frequently and your test data can be updated or deleted.

https://sandbox.belvo.co/

Production

The production environment is dedicated to live applications with real connections to institutions.
In this environment, you will need real credentials to create links and you will pull real data from the institutions.

https://api.belvo.co/

If you want to know more about our Sandbox environment and how to use it, you can read our guide to test in Sandbox.

Error handling

We use the following HTTP status code in the response depending on the success or failure:

Code

Description

200

:white-check-mark: Success - The content is available in the response body.

201

:white-check-mark: Success - The content was created successfully on Belvo.

204

:white-check-mark: Success - No content to return.

400

:no-entry: Bad Request Error - The detail of the error is available in the response body.

401

:no-entry: Unauthorized - The Belvo credentials you are using are not valid.

404

:no-entry: Not found - The resource you are trying to access cannot be found.

428

:no-entry: MFA Token Required - The institution required a token, you can resume after giving the token.

500

:no-entry: Internal Server Error - The detail of the error is available in the response body.

You can find a full description of each error code by endpoint in our API reference.

Retry policy

Here is our recommendation in terms of retry on errors:

  • for 50x errors, our recommendation is to implement an automated exponential backoff, up to 5 retries, with a base interval of 3 seconds and factor of 2 (1st retry after 3 seconds, 2nd retry after 2*3=6 seconds, 3rd retry after 2*6=12 seconds, etc... up to 48s).
  • For 40x errors, your should not retry as it is a client error. The only exception is with the “Too Many Sessions” error (which corresponds to a client asking to access the same account multiple times in parallel). This is a transient error that can be retried using the same backoff strategy as above.

Advanced topics

You should now be ready to start building with Belvo API.

We also created dedicated guides for the following advanced topics:

Updated about 21 hours ago



Build with Belvo API


Suggested Edits are limited on API Reference Pages

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