Sandbox

Enjoy unlimited testing to speed up your integration with our sandbox environment 🤘.

With Belvo's sandbox environment, you can interact with dummy banking, fiscal, and gig data to prototype your integration. In this article, we'll provide you reference documentation on what resources are available and in which use cases you can apply them.

You can use all the same API calls as per our API reference, but just change the base URL to https://sandbox.belvo.com/api/.

Accessing the sandbox

To access the sandbox, just make sure to generate your sandbox API keys and use the https://sandbox.belvo.com/api/ base URL.

Test it Out!
To make sure that everything is working as expected, try out the following API call in the sandbox environment. If you've used the right keys, you'll see a list of institutions in the response.

curl --request GET  https://sandbox.belvo.com/api/institutions/  \
-u Your-Sandbox-Secret-ID:Your-Sandbox-Secret-Password

Sandbox Institutions and Data

To help you simulate real-world interactions you can use our mock data sets for banking, fiscal, and gig-economy use cases.

❗️

Sandbox Data

Please note that we refresh the sandbox environment on the first day of every month, which means that all your sandbox data (created links, account information, and so on) will be deleted.

👍

Unlimited links and pagination

Unlimited links
Apart from the login credentials we provide, you can also use any combination of username and password to create more links. The data associated with these links will contain the same information as a frequent user (that is, one that has a username ending in 100).

Pagination
Our sandbox environment returns 10 results per page (in contrast to 100 in our development and production environments). This lets you implement pagination logic in your integration without having to create hundreds of links.

Banking

To test banking institutions that do not require MFAMFA - Multi-Factor Authentication (MFA) is an additional step where the user must provide an authentication token to gain access to their account., you can use the following retail institutions:

Erebor Bank

  • erebor_mx_retail
  • erebor_co_retail
  • erebor_br_retail

Gringotts Bank

  • gringotts_mx_retail
  • gringotts_co_retail
  • gringotts_br_retail

Gotham Business Bank

  • gotham_mx_business
  • gotham_co_business
  • gotham_br_business

You can simulate different types of users by using the following login credentials when registering a link:

Username

Password

Use to simulate...

Accounts

Balances

Incomes

Owners

Transactions

bnk100

full

A user that uses their bank accounts often.

Up to 4*

Up to 3

2 or more

1

Over 100, paginated

bnk101

nodata

A user that has has just opened their bank account or has never used it.

None

None

None

None

None

bnk102

low

A user that does not use their bank account often.

Up to 2

Up to 2

None

1

Up to 5

bnk103

negative

A user that has overdrawn accounts.

Up to 2

Up to 2

None

1

Up to 5

* For Brazillian institutions, we also return a pension fund (previdencia) account.

📘

Statements resource in the sandbox environment

At the moment, we don't support the Statements endpoint in our sandbox environment. However, if it is something you'd like us to support, just contact us at [email protected].

Fiscal

To test fiscal institutions, you can use the following institution:

Tatooine Fiscal

  • tatooine_mx_fiscal

You can simulate different types of users by using the following login credentials when registering a link:

Username

Password

Use to simulate...

Invoices

Tax compliance status

Tax returns

Tax status

PMO010101000

business

A business

100 (20 invoices per year), paginated

1

5 business tax returns (one per year)

1 business tax status

PFIS010101000

individual

An individual

100 (20 invoices per year), paginated

1

5 individual tax returns (one per year)

1 individual tax status

NULL010101000

nodata

A business or individual that has submitted no information to the fiscal authority.

None

None

None

None

Gig

To test gig-economy institutions (such as Uber or Rappi), you can use the following institutions:

Goonies

A ride-sharing company

  • goonies_mx_gig
  • goonies_co_gig
  • goonies_br_gig

Planet Express

A delivery company

  • planet_mx_gig
  • planet_co_gig
  • planet_br_gig

You can simulate different types of users by using the following login credentials when registering a link:

Username

Password

Use to simulate...

Accounts

Owners

Transactions

gig100

full

A regularly active gig worker.

1

1

Over 40, paginated

gig101

nodata

A new or inactive gig worker.

None

None

None

gig102

low

A gig worker that does not work regularly.

1

1

Up to 5

gig103

negative

A gig worker with a negative balance.

1

1

Up to 5

Login Flows

Standard

When you want to test standard user login flows for an API or widget, you can use these credentials for any institution:

Flow

Username

Password

API response

Valid credentials

user_valid

pass_valid

200 Success

Invalid credentials

user_invalid

pass_invalid

400 Login Error

Validation error

1234567890abcdefg

1234567890abcdefg

400 Validation Error

Advanced (MFA)

👍

Most real-world institutions require MFA as part of their login process. Please make sure to thoroughly test out the different used cases to improve your integration. For more information on types of MFA you can encounter, check out our Handling multi-factor authentication article.

When you want to test out user login flows that require MFAMFA - Multi-Factor Authentication (MFA) is an additional step where the user must provide an authentication token to gain access to their account., you can use the following institution:

Heimdall Bank

  • heimdall_mx_retail
  • heimdall_co_retail
  • heimdall_br_retail

Depending on the flow you want to simulate, use the appropriate username and password:

Username

Password

Use to simulate a flow where...

mfa_default

pass_valid

A user needs to generate an MFA token using a mobile or other device.

mfa_numeric

numeric_code

A user needs to input a challenge code in order to generate the MFA token.

mfa_qr

qr_code

A user needs to scan a QR code in order to generate the MFA token.

After you use one of these credentials, you'll receive a 428 Token Required Error response. You'll need to send a PATCH request with one of the following tokens to finish creating the link.

Use case

Token

API Response

Valid token

111111

201 Created

Invalid token

999999

428 Token Required

Here's an example flow:

{
    "institution": "heimdall_mx_retail",
    "username": "mfa_numeric",
    "password": "numeric_code"
}
[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "731b8a5ed45245b3a2bd595382016b5e",
        "expiry": "720",
        "link": "04134743-73f9-41c3-a6dd-06cee3fab627",
        "token_generation_data": {
            "instructions": "Use this code to generate the token",
            "type": "numeric",
            "value": "703837"
        },
        "request_id": "63cece2a9374b06495a16da5b2265793"
    }
]
{
    "session": "731b8a5ed45245b3a2bd595382016b5e",
    "token": "111111",
    "link": "04134743-73f9-41c3-a6dd-06cee3fab627"
}
{
    "id": "04134743-73f9-41c3-a6dd-06cee3fab627",
    "institution": "heimdall_mx_retail",
    "access_mode": "recurrent",
    "status": "valid",
    "created_by": "7e229417-9899-4447-a422-622ef8f9fa08",
    "last_accessed_at": "2021-02-09T11:48:32.550694Z"
}

Or, to make things easier, just use our Connect Widget:

MFA handling with the Connect Widget in SandboxMFA handling with the Connect Widget in Sandbox

MFA handling with the Connect Widget in Sandbox

📘

Widget update mode

In order for you to be able to test out using our Connect Widget in Update mode, any additional POST requests that you make to a link created at Heimdall (for example, to retrieve transactions) will return a 428 Token Required response.

Advanced (Non-MFA)

When you want to test out advanced user login flows that require additional username_type, username2, or password2 parameters, you can use the following institution and credentials:

Iron Bank

  • ironbank_mx_retail
  • ironbank_co_retail
  • ironbank_br_retail

Depending on the flow you want to simulate, use the appropriate username, password, and additional parameters:

Use case

Username

Password

Username Type

Username 2

Password 2

API Response

Valid credentials

adv_valid

pass_valid

003

valid

valid

200 Success

Invalid credentials

adv_invalid

pass_invalid

999

invalid

invalid

400 Login Error

Additional resources


Did this page help you?