Connect to any financial institution in Latin America with Belvo.

Build fintech innovations on top of any banking, fiscal and gig institutions in Latam.


Get started

Test with cURL & libraries

Learn how to connect with a financial institution and access your first financial using cURL or libraries.

Belvo offers two environments:

  • Sandbox, a test environment with fake data for development phases
  • Production, a live environment used with real connections to institutions

To generate your keys for each environment, check our guide to get your Belvo API keys.

👍

In the following examples we will use the production environment.
Change the base URL to https://sandbox.belvo.co for each example to switch to sandbox.

List institutions

Start by listing all institutions supported by Belvo:

# For production
curl https://api.belvo.co/api/institutions/  \
  -u [Secret Key ID]:[Secret Key PASSWORD]
# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from pprint import pprint
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://api.belvo.co")

# List institutions
for institution in client.Institutions.list():
    pprint(institution)
# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
)

sandbox.institutions.list
// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
);

client.connect()
  .then(function () {
    client.institutions.list()
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

It will return a list of institutions:

{
    "count": 10,
    "next": null,
    "previous": null,
    "results": [
        ...
        {
            "name": "banamex_mx_retail",
            "type": "bank",
            "website": "https://www.banamex.com/",
            "display_name": "Citibanamex",
            "country_codes": [
                "MX"
            ],
            "primary_color": "#056dae",
            "logo": "https://belvo-api-media-sta.s3.amazonaws.com/logos/citibanamex_logo.png",
            "form_fields": [
                ...
            ]
        },
        ...
    ]
}

Register a link

Based on the previous list, we will register a LinkLink - A Link is a set of credentials associated to an 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. with one of the supported institutions.

🚧

Production vs. Sandbox

Testing with the production environment, you will have to use the credentials of a real bank account to perform this step.
Testing with the sandbox environment, any value as username and password will work and create successfully the link.

Register a first link by sending a POST request to our Links resource:

curl -X POST \
  https://api.belvo.co/api/links/ \
  -H 'Content-Type: application/json' \
  -H 'Host: api.belvo.co' \
  -d '{
    "institution": "[INSTITUTION_NAME]",
    "username": "[BANK_USERNAME]",
    "password": "[BANK_PASSWORD]"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]
# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://api.belvo.co")

# Register a link
link = client.Links.create(
    institution="[INSTITUTION_NAME]",
    username="[BANK_USERNAME]",
    password="[BANK_PASSWORD]"
)
# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
)

sandbox.links.register(
  institution: '[INSTITUTION_NAME]',
  username: '[BANK_USERNAME]',
  password: '[BANK_PASSWORD]'
)
// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
);

client.connect()
  .then(function () {
    client.links.register('[INSTITUTION_NAME]', '[BANK_USERNAME]', '[BANK_PASSWORD]')
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

Where:

  • [INSTITUTION_NAME] is the name of the institution, e.g. "banamex_mx_retail"
  • [BANK_USERNAME] is the username used to sign in online to the institution
  • [BANK_PASSWORD] is the password used to sign in online to the institution

If the credentials are correct, you will receive a 201 success response:

{
    "id": "8296c694-c629-48fe-a29a-dea595987a3e",
    "institution": "banamex_mx_retail",
    "access_mode": "single",
    "last_accessed_at": "2019-10-30T12:39:18.014131Z",
    "status": "valid"
}

Retrieve accounts

Retrieve the bank accounts information by sending a POST request to our Accounts resource:

curl -X POST \
  https://api.belvo.co/api/accounts/ \
  -H 'Content-Type: application/json' \
  -H 'Host: api.belvo.co' \
  -H 'cache-control: no-cache' \
  -d '{
    "link": "[LINK_ID]"
}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]
# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://api.belvo.co")

# Retrieve accounts
accounts = client.Accounts.create(
  link="8296c694-c629-48fe-a29a-dea595987a3e"
)
# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
)

sandbox.accounts.retrieve link: '8296c694-c629-48fe-a29a-dea595987a3e'
// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
);

client.connect()
  .then(function () {
    client.accounts.retrieve('8296c694-c629-48fe-a29a-dea595987a3e')
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

Where:

  • [LINK_ID] is the ID of the link created in the previous step

You will receive a 201 success response:

[
   {
      "id":"2c9a00c3-0618-4283-ad6b-eb6cd83d1b1a",
      "type":"SUPER NOMINA",
      "name":"SUPER NOMINA",
      "number":"00000000000000001234",
      "category":"CHECKING_ACCOUNT",
      "collected_at":"2019-10-30T12:53:59.181659Z",
      "bank_product_id":"01",
      "currency":"MXN",
      "balance": {
        "current": 6424.03,
        "available": 6424.03
      },
      "public_identification_name":"CLABE",
      "public_identification_value":"000000000000023456",
      "link":"8296c694-c629-48fe-a29a-dea595987a3e",
      "internal_identification":"12345678901",
      "institution":{
         "name":"banamex_mx_retail",
         "type":"bank"
      },
      "credit_data":null
   }
]

Retrieve transactions

Retrieve the transactions information by sending a POST request to our Transactions resource:

curl -X POST \
  https://api.belvo.co/api/transactions/ \
  -H 'Content-Type: application/json' \
  -H 'Host: api.belvo.co' \
  -H 'cache-control: no-cache' \
  -d '{
    "link": "[LINK_ID]"
    "date_from": "2019-06-30",
    "date_to": "2019-10-30"
}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]
# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://api.belvo.co")

# Retrieve transactions
transactions = client.Transactions.create(
  "8296c694-c629-48fe-a29a-dea595987a3e",
  "2019-06-30",
  date_to="2019-10-30",
  account="2c9a00c3-0618-4283-ad6b-eb6cd83d1b1a"
)
# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.co'
)

sandbox.transactions.retrieve(
  link: '8296c694-c629-48fe-a29a-dea595987a3e',
  date_from: '2019-06-30',
  options: {
    date_to: '2019-10-30',
    account: '2c9a00c3-0618-4283-ad6b-eb6cd83d1b1a'
  }
)
// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://sandbox.belvo.co'
);

client.connect()
  .then(function () {
    client.transactions.retrieve('8296c694-c629-48fe-a29a-dea595987a3e', '2019-06-30', { 'dateTo': '2019-10-30', 'account': '2c9a00c3-0618-4283-ad6b-eb6cd83d1b1a' })
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

Where:

  • [LINK_ID] is the ID of the link created in the previous step

You will receive a 201 success response:

[
   {
      "id":"87bbf2c4-9613-4b91-bff6-2ddcbcc479c5",
      "collected_at":"2019-10-30T12:54:00.028177Z",
      "value_date":"2019-09-07T15:01:00Z",
      "accounting_date":null,
      "amount":"1.00",
      "balance":"3013.18",
      "currency":"MXN",
      "description":"UBERX Trip 12345",
      "reference":"00000001",
      "type":"OUTFLOW",
      "status":"UNCATEGORIZED",
      "account":{
        "id":"2c9a00c3-0618-4283-ad6b-eb6cd83d1b1a",
        "type":"SUPER NOMINA",
        "name":"SUPER NOMINA",
        "number":"00000000000000001234",
        "category":"CHECKING_ACCOUNT",
        "collected_at":"2019-10-30T12:53:59.181659Z",
        "bank_product_id":"01",
        "currency":"MXN",
        "balance": {
          "current": 6424.03,
          "available": 6424.03
        },
        "public_identification_name":"CLABE",
        "public_identification_value":"000000000000023456",
        "link":"8296c694-c629-48fe-a29a-dea595987a3e",
        "internal_identification":"12345678901",
        "institution":{
          "name":"banamex_mx_retail",
          "type":"bank"
        },
        "credit_data":null
      }
   }
]

Delete the link

Delete permanently the data and unlink the bank account from Belvo by sending a DELETE request to our Links resource:

curl -X DELETE \
  https://api.belvo.co/api/links/[LINK_ID]/ \
  -H 'Host: api.belvo.co' \
  -u  [Secret Key ID]:[Secret Key PASSWORD]
# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://api.belvo.co")

client.Links.delete("8296c694-c629-48fe-a29a-dea595987a3e")
# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
)

sandbox.links.delete id: '8296c694-c629-48fe-a29a-dea595987a3e'
// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
);

client.connect()
  .then(function () {
    client.links.delete('8296c694-c629-48fe-a29a-dea595987a3e')
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

Where:

  • [LINK_ID] is the ID of the link created in the previous step

You will receive a 204 success response with no content.

Validate the deletion by listing all registered Links for you key:

curl https://api.belvo.co/api/links/ \
  -u [Secret Key ID]:[Secret Key PASSWORD]
# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from pprint import pprint
from belvo.client import Client

# Login to Belvo API
client = Client("Secret Key ID", "Secret Key PASSWORD", "https://api.belvo.co")

# List links
for link in client.Links.list():
    pprint(link)
# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

sandbox = Belvo::Client.new(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
)

sandbox.links.list
// check our node package on github
// https://github.com/belvo-finance/belvo-js

var belvo = require('belvo').default;

var client = new belvo(
  'Secret Key ID',
  'Secret Key PASSWORD',
  'https://api.belvo.co'
);

client.connect()
  .then(function () {
    client.links.list()
      .then(function (res) {
        console.log(res);
      })
      .catch(function (error) {
        console.log(error);
      });
});

Updated about a month ago



Test with cURL & libraries


Suggested Edits are limited on API Reference Pages

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