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

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.

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.

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.

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.

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:

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.

Incomes ^BETA

📘

The incomes 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 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 type bank.

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

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.

📘

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 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).

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.

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.

Transactions

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

Owners

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

Balances

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

Integration overview

HTTP Methods

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

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.

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:

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:

• Test in Sandbox
• Handling 2-Factor Authentication
• Searching and filtering