Learn how to build in details your integration with Belvo API.
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 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 a new link from a financial institution to your Belvo account. | |
| List of all links currently associated with your Belvo account. | |
| Resume a link registering session that was paused because a MFA token was required by the institution. | |
| Get the details of a specific link. | |
| Update the password of a specific link. | |
| 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 and gig 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 and gig 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 according to your recurrent link frequency, starting every day at
14.30 UTC
:
- 6h, all recurrent links will be refreshed every 6h (4 times a day)
- 12h, all recurrent links will be refreshed every 12h (2 times a day)
- 24h (default), all recurrent links will be refreshed 1 time a day.
- contact us at [email protected] if you want to change the update frequency of your recurrent links
- custom
encryption_key
cannot be used for recurrent links, our own secret must be used to encrypt the link
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 |
invalid | An |
unconfirmed | An |
token_required | A |
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 typebank
orgig
.
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 all accounts related to a specific link. | |
| List all the accounts from all the Links already associated with your Belvo account. | |
| Resume an account retrieving session that was paused because a MFA token was required by the institution. | |
| Get the details of a specific account. | |
| 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 typebank
orgig
.
A Transaction
contains the detailed information of each movement inside an Account
.
Endpoints | Method | Description |
---|---|---|
| Retrieve all transactions related to a specific account within a specified data range. | |
| List all transactions already associated with your Belvo account. | |
| Resume a transaction retrieving session that was paused because a MFA token was required by the institution. | |
| Get the details of a specific transaction. | |
| Delete permanently a transaction from your Belvo account. |
Transaction categorization
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" |
Balances
The
balance
resource is only available for the links created with institutions of typebank
.
A Balance
represents the financial status of an Account at a given time.
Endpoints | Method | Description |
---|---|---|
| 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 all existing balances in your Belvo account. | |
| Resume a Balance retrieve session that was paused because a MFA token was required by the institution. | |
| Get the details of a specific balance. | |
| Delete a specific balance from your Belvo account. |
Incomes BETA
The
incomes
resource is only available for the links created with institutions of typebank
.
An Income
represents a list of insights about the income of a user through its bank Accounts
.
The Incomes insights resource is currently in BETA version.
Contact us at [email protected] if you want to be part of this BETA.
Owners
The
owner
resource is only available for the links created with institutions of typebank
.
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 the owner detail of a specific link. | |
| List all owners associated to your Belvo account. | |
| Resume a owner retrieving session that was paused because a MFA token was required by the institution. | |
| Get the details of a specific owner. | |
| 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 typefiscal
.
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
.
SAT imposes limits on the number of invoices you can download per day. For more information, as well as potential workarounds, see our help center article.
Tax returns
The
tax return
resource is only available for the links created with institutions of typefiscal
.
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).
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 typefiscal
.
The tax status data structure will be different depending on if it is related to a person or a business.
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 all accounts related to a specific link. | |
| List all the accounts from all the Links already associated with your Belvo account. | |
| Resume an account retrieving session that was paused because a MFA token was required by the institution. | |
| Get the details of a specific account. | |
| 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 all transactions related to a specific link. | |
| List all the transactions from all the Links already associated with your Belvo account. | |
| Resume a transactions retrieving session that was paused because a MFA token was required by the institution. | |
| Get the details of a specific transaction. | |
| 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 all owners related to a specific link. | |
| List all the owners from all the Links already associated with your Belvo account. | |
| Resume an owner retrieving session that was paused because a MFA token was required by the institution. | |
| Get the details of a specific owner. | |
| 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 all balances related to a specific link. | |
| List all the balances from all the Links already associated with your Belvo account. | |
| Resume a balance retrieving session that was paused because a MFA token was required by the institution. | |
| Get the details of a specific balance. | |
| 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 |
---|---|
| 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. |
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 ⚠️ The sandbox environment is refreshed frequently and your test data can be updated or deleted. | |
Production | The |
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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 2 days ago
What's Next
API reference |
Resources |
Test in Sandbox |