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 ›

Sandbox

📘

In this section, you will learn how to access Sandbox and start testing Belvo products,

Belvo is providing a sandbox environment to help you test the API without having to provide real institution credentials.
This environment is dedicated to tests, you must use the production environment for live integration with end users.

Access the sandbox environment

To get access to our sandbox environment you will need to register to Belvo.

Once you access Belvo's dashboard, you can create a Sandbox secret key.

  • Go to the Summary menu and the Sandbox environment
  • Expand the secret key section and it will automatically generate one for you
  • Your sandbox secret ID and Password will be shown and you can copy it

🚧

Secret Password

For security reason, your Sandbox secretPassword will be revealed only once after generation. Make sure to copy it and save it. If you have lost your sandbox secretPassword, you can always regenerate it from the dashboard.

The base URL for the sandbox environment is https://sandbox.belvo.co

To check that everything is working correctly, you can try the following API request to list Belvo's supported institutions.

curl -u [Secret Key ID]:[Secret Key PASSWORD] https://sandbox.belvo.co/api/institutions/

You should receive a response from Belvo with the list of all supported institutions in Sandbox.

{
    "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": [
                {
                    "name": "username",
                    "type": "text",
                    "label": "Client number"
                },
                {
                    "name": "password",
                    "type": "password",
                    "label": "Key BancaNet"
                }
            ]
        }
      ...
    ]
}

Create links in Sandbox

You can create links in Sandbox using the Register endpoint.
Make sure to use the following based URL:

https://sandbox.belvo.co/

📘

Single and recurrent links

You can create and test single and recurrent links in our sandbox environment.
More about the differences between recurrent and single link in our dedicated guide.

Test credentials

Test the default flow

To create a link with any institution, use any value for username and password.
Any value will be valid and result in a 201 success response with the link created and ready to be used.
Example of default flow for link creation in Sandbox:

curl -X POST \
  https://sandbox.belvo.co/api/links/ \
  -H 'Content-Type: application/json' \
  -d '{
    "institution": "banamex_mx_retail",
    "username": "user_valid",
    "password": "pass_valid"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Test invalid credentials

You can test the invalid credential flow by using invalid as a username with any institution.
This will result in a 400 LoginError response and the link will not be created.
Example of invalid credentials flow for link creation in Sandbox:

curl -X POST \
  https://sandbox.belvo.co/api/links/ \
  -H 'Content-Type: application/json' \
  -d '{
    "institution": "banamex_mx_retail",
    "username": "invalid",
    "password": "pass_valid"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Test the 2FA

In order to test the 2FA flow you will need to use the bancomer_mx_retail institution.
This institution is setup to require a 2FA token to create the link.

You have 2 options:

Option 1: Send the token during the link creation

In this case, you can pass any token while registering the link:

curl -X POST \
  https://sandbox.belvo.co/api/links/ \
  -H 'Content-Type: application/json' \
  -d '{
    "institution": "bancomer_mx_retail",
    "username": "user_valid",
    "password": "pass_valid",
    "token": "any"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

This will result in a 201 success response with the link created and ready to be used.

Option 2: Send the token after the link creation

You can also do a 2 step process to send the token.

First, create the link:

curl -X POST \
  https://sandbox.belvo.co/api/links/ \
  -H 'Content-Type: application/json' \
  -d '{
    "institution": "bancomer_mx_retail",
    "username": "user_valid",
    "password": "pass_valid"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

This will result in a 428 MFA Token Required response with a link_id and a session_id:

{
    "detail": "A MFA token is required by the institution to login",
    "session": "3752e47e4b68487ab20291ab8e39a31e",
    "expiry": "720",
    "link": "763f556d-059c-4d14-80cc-019d76a77a9c"
}

Then, you resume the link creation session with the token:

curl -X PATCH \
  https://sandbox.belvo.co/api/links/ \
  -H 'Content-Type: application/json' \
  -d '{
    "session": "3752e47e4b68487ab20291ab8e39a31e",
    "token": "any",
    "link": "763f556d-059c-4d14-80cc-019d76a77a9c"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

This will result in a 201 success response with the link created and ready to be used.

Test the session expiration

Using this Option 2, you have the possibility to test the session expiration of a link creation.
For that, you just need to wait at least 12 minutes between the two steps of the option 2:

  • link creation
  • wait 12 minutes
  • link resume

This will result in a 400 SessionExpiredError response and the link will have to be recreated.

Test different types of 2FA

It is possible to simulate the different options encountered by users to generate the 2FA token.
Using different password field values when registering a link with the bancomer_mx_retail institution, you can trigger different 2FA flows:

Password value

Description

anything

Simulate the default case, where the user needs to generate the 2FA token using its mobile or dedicated device.

Example of 428 error in this case:

{
  "detail": "A MFA token is required by the institution to login",
  "session": "2675b703b9d4451f8d4861a3eee54449",
  "expiry": 9600,
  "link": "30cb4806-6e00-48a4-91c9-ca55968576c8"
}

qr_code

Simulate the case where the user needs to scan a QR code in order to generate the 2FA token.

Example of 428 error in this case:

{
  "detail": "A MFA token is required by the institution to login",
  "session": "2675b703b9d4451f8d4861a3eee54449",
  "expiry": 9600,
  "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "token_generation_data": {
    "instructions": "Scan this QR code to generate the token",
    "type": "qr",
    "value": "bynaryofpicture"
  }
}

numeric_code

Simulate the case where the user needs to input a challenge code in order to generate the 2FA token.

Example of 428 error in this case:

{
  "detail": "A MFA token is required by the institution to login",
  "session": "2675b703b9d4451f8d4861a3eee54449",
  "expiry": 9600,
  "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "token_generation_data": {
    "instructions": "Use this code to generate the token",
    "type": "numeric",
    "value": "12345"
  }
}

Access data in Sandbox

Once you have links created, you can use any of the resources (accounts, transactions, owners, invoices, tax returns, ...) to pull data.

To simulate the connection with the institution to pull data you will always need to call the Retrieve endpoints first on accounts, transactions or owners.

curl -X POST \
  https://sandbox.belvo.co/api/accounts/ \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "link": "link_id"
}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]
curl -X POST \
  https://sandbox.belvo.co/api/transactions/ \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "link": "link_id",
    "account": "account_id",
    "date_from": "2019-06-30",
    "date_to": "2019-10-30"
}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]
curl -X POST \
  https://sandbox.belvo.co/api/owners/ \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "link": "link_id"
}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Each of this call will generate test data for the link and save it in your sandbox environment, for example:

[
    {
        "id": "cd6a8b09-000f-4494-865c-4fcba90cc849",
        "link": "77cedd08-5450-425c-95d2-075d8865dcb0",
        "institution": {
            "name": "banamex_mx_retail",
            "type": "retail"
        },
        "internal_identification": "4f5716a0",
        "name": "Crédito",
        "number": "11427134",
        "type": "Créditos",
        "category": "LOAN_ACCOUNT",
        "bank_product_id": "46",
        "public_identification_name": "ACCOUNT_NUMBER",
        "public_identification_value": "11427134",
        "currency": "MXN",
        "balance": {
            "current": -24197.34,
            "available": 0.0
        },
        "credit_data": null,
        "loan_data": null,
        "collected_at": "2019-11-21T15:12:51.140640",
        "last_accessed_at": "2019-11-20T22:26:22"
    },
    {
        "id": "52bc119a-f19a-47be-bfe1-44cfd7618b68",
        "link": "77cedd08-5450-425c-95d2-075d8865dcb0",
        "institution": {
            "name": "banamex_mx_retail",
            "type": "retail"
        },
        "internal_identification": "c22fd531",
        "name": "Tarjeta Platino",
        "number": "18211110",
        "type": "Tarjetas de crédito",
        "category": "CREDIT_CARD",
        "bank_product_id": "76",
        "public_identification_name": "CREDIT_CARD_NUMBER",
        "public_identification_value": "4821255137460",
        "currency": "MXN",
        "balance": {
            "current": -9794.4,
            "available": 12020.12
        },
        "credit_data": null,
        "loan_data": null,
        "collected_at": "2019-11-21T15:12:51.140453",
        "last_accessed_at": "2019-11-21T03:21:33"
    },
    {
        "id": "0e2dcf78-f384-487c-b058-112c8d7fc95a",
        "link": "77cedd08-5450-425c-95d2-075d8865dcb0",
        "institution": {
            "name": "banamex_mx_retail",
            "type": "retail"
        },
        "internal_identification": "17322eee",
        "name": "Cuenta perfiles",
        "number": "46006889",
        "type": "Cuentas de efectivo",
        "category": "CHECKING_ACCOUNT",
        "bank_product_id": "56",
        "public_identification_name": "CLABE",
        "public_identification_value": "905274581194455593",
        "currency": "MXN",
        "balance": {
            "current": 37702.59,
            "available": 37702.59
        },
        "credit_data": null,
        "loan_data": null,
        "collected_at": "2019-11-21T15:12:51.140170",
        "last_accessed_at": "2019-11-21T12:37:58"
    }
]
[
    {
        "id": "c8b553cd-3b3b-4ca0-98df-081454fbb4b2",
        "account": {
            "id": "cd6a8b09-000f-4494-865c-4fcba90cc849",
            "link": "77cedd08-5450-425c-95d2-075d8865dcb0",
            "institution": {
                "name": "banamex",
                "type": "retail"
            },
            "internal_identification": "4f5716a0",
            "name": "Crédito",
            "number": "11427134",
            "type": "Créditos",
            "category": "LOAN_ACCOUNT",
            "bank_product_id": "46",
            "public_identification_name": "ACCOUNT_NUMBER",
            "public_identification_value": "11427134",
            "currency": "MXN",
            "balance": {
                "current": -24197.34,
                "available": 0.0
            },
            "credit_data": null,
            "loan_data": null,
            "collected_at": "2019-11-21T15:12:51.140640",
            "last_accessed_at": "2019-11-20T22:26:22"
        },
        "internal_identification": "0619",
        "value_date": "2019-11-12T20:12:11",
        "accounting_date": null,
        "amount": -178.68,
        "currency": "MXN",
        "description": "Expedita error laborum libero possimus aperiam. Distinctio voluptate iusto iure sit ut error officia. Dignissimos quae possimus nesciunt explicabo incidunt beatae at.",
        "reference": "7400",
        "observations": null,
        "balance": 4625.41,
        "status": "UNCATEGORIZED",
        "type": "OUTFLOW",
        "collected_at": "2019-11-21T15:12:51.155757"
    },
    {
        "id": "b04878e3-8f9e-4323-9f49-f337758851de",
        "account": {
            "id": "cd6a8b09-000f-4494-865c-4fcba90cc849",
            "link": "77cedd08-5450-425c-95d2-075d8865dcb0",
            "institution": {
                "name": "banamex",
                "type": "retail"
            },
            "internal_identification": "4f5716a0",
            "name": "Crédito",
            "number": "11427134",
            "type": "Créditos",
            "category": "LOAN_ACCOUNT",
            "bank_product_id": "46",
            "public_identification_name": "ACCOUNT_NUMBER",
            "public_identification_value": "11427134",
            "currency": "MXN",
            "balance": {
                "current": -24197.34,
                "available": 0.0
            },
            "credit_data": null,
            "loan_data": null,
            "collected_at": "2019-11-21T15:12:51.140640",
            "last_accessed_at": "2019-11-20T22:26:22"
        },
        "internal_identification": "7095",
        "value_date": "2019-11-08T05:38:50",
        "accounting_date": null,
        "amount": -8883.6,
        "currency": "MXN",
        "description": "Minima sunt ullam doloremque at ipsam. Error aliquam soluta magnam officia esse. Ipsa necessitatibus dolorem earum illo sequi.",
        "reference": "2204",
        "observations": null,
        "balance": 38872.7,
        "status": "PENDING",
        "type": "OUTFLOW",
        "collected_at": "2019-11-21T15:12:51.157225"
    }
]
[
    {
        "id": "70281871-ace3-4df0-87a9-82d7666453b7",
        "accounts": [
            {
                "id": "0e2dcf78-f384-487c-b058-112c8d7fc95a",
                "link": "77cedd08-5450-425c-95d2-075d8865dcb0",
                "institution": {
                    "name": "banamex",
                    "type": "retail"
                },
                "name": "Cuenta perfiles",
                "type": "Cuentas de efectivo",
                "number": "46006889",
                "balance": {
                    "current": 37702.59,
                    "available": 37702.59
                },
                "category": "CHECKING_ACCOUNT",
                "currency": "MXN",
                "loan_data": null,
                "credit_data": null,
                "collected_at": "2019-11-21T15:12:51.140170",
                "bank_product_id": "56",
                "last_accessed_at": "2019-11-21T12:37:58",
                "internal_identification": "17322eee",
                "public_identification_name": "CLABE",
                "public_identification_value": "905274581194455593"
            },
            {
                "id": "52bc119a-f19a-47be-bfe1-44cfd7618b68",
                "link": "77cedd08-5450-425c-95d2-075d8865dcb0",
                "institution": {
                    "name": "banamex",
                    "type": "retail"
                },
                "name": "Tarjeta Platino",
                "type": "Tarjetas de crédito",
                "number": "18211110",
                "balance": {
                    "current": -9794.4,
                    "available": 12020.12
                },
                "category": "CREDIT_CARD",
                "currency": "MXN",
                "loan_data": null,
                "credit_data": null,
                "collected_at": "2019-11-21T15:12:51.140453",
                "bank_product_id": "76",
                "last_accessed_at": "2019-11-21T03:21:33",
                "internal_identification": "c22fd531",
                "public_identification_name": "CREDIT_CARD_NUMBER",
                "public_identification_value": "4821255137460"
            },
            {
                "id": "cd6a8b09-000f-4494-865c-4fcba90cc849",
                "link": "77cedd08-5450-425c-95d2-075d8865dcb0",
                "institution": {
                    "name": "banamex",
                    "type": "retail"
                },
                "name": "Crédito",
                "type": "Créditos",
                "number": "11427134",
                "balance": {
                    "current": -24197.34,
                    "available": 0.0
                },
                "category": "LOAN_ACCOUNT",
                "currency": "MXN",
                "loan_data": null,
                "credit_data": null,
                "collected_at": "2019-11-21T15:12:51.140640",
                "bank_product_id": "46",
                "last_accessed_at": "2019-11-20T22:26:22",
                "internal_identification": "4f5716a0",
                "public_identification_name": "ACCOUNT_NUMBER",
                "public_identification_value": "11427134"
            }
        ],
        "link": "77cedd08-5450-425c-95d2-075d8865dcb0",
        "internal_identification": "09fe61f3",
        "display_name": "Camilo Corona Lozano",
        "first_name": "Camilo",
        "last_name": "Corona",
        "second_last_name": "Lozano",
        "email": "[email protected]",
        "phone_number": "(643)573-8847",
        "address": "Prolongación Veracruz de Ignacio de la Llave 536 Interior 003\nNueva Bangladesh, COL 73483",
        "collected_at": "2019-11-21T15:12:51.133945",
        "raw_json": null
    }
]

Once you have done the retrieve, you can use the other endpoints to list, get or destroy resources.

Data update in Sandbox

In order to keep our sandbox environment reliable, we clean it frequently.
Every month, on day 1, your test data (links, account, transactions and owners) will be deleted.

Updated 3 days ago



Sandbox


Suggested Edits are limited on API Reference Pages

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