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 MFA, 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:

UsernamePasswordUse to simulate...AccountsBalancesIncomesOwnersTransactions
bnk100fullA user that uses their bank accounts often.Up to 4*More than 111Over 100, paginated
bnk101nodataA user that has has just opened their bank account or has never used it.NoneNoneNoneNoneNone
bnk102lowA user that does not use their bank account often.Up to 2More than 1None1Up to 5
bnk103negativeA user that has overdrawn accounts.Up to 2More than 1None1Up to 5

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

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:

UsernamePasswordUse to simulate...InvoicesTax compliance statusTax returnsTax status
PMO010101000businessA business100 (20 invoices per year), paginated15 business tax returns (one per year)1 business tax status
PFIS010101000individualAn individual100 (20 invoices per year), paginated15 individual tax returns (one per year)1 individual tax status
NULL010101000nodataA business or individual that has submitted no information to the fiscal authority.None (returns an empty array)1None (returns an empty array)1 individual tax status

Gig

🚧

Sunset notice: Our Gig economy product is due to be sunsetted soon. After which, we will no longer support this product.

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:

UsernamePasswordUse to simulate...AccountsOwnersTransactions
gig100fullA regularly active gig worker.11Over 40, paginated
gig101nodataA new or inactive gig worker.NoneNoneNone
gig102lowA gig worker that does not work regularly.11Up to 5
gig103negativeA gig worker with a negative balance.11Up 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:

FlowUsernamePasswordAPI response
Valid credentialsuser_validpass_valid200 Success
Invalid credentialsuser_invalidpass_invalid400 Login Error
Validation error1234567890abcdefg1234567890abcdefg400 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 MFA, 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:

UsernamePasswordUse to simulate a flow where...
mfa_defaultpass_validA user needs to generate an MFA token using a mobile or other device.
mfa_numericnumeric_codeA user needs to input a challenge code in order to generate the MFA token.
mfa_qrqr_codeA 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 caseTokenAPI Response
Valid token111111201 Created
Invalid token999999428 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-12-07T16:06:49.731705Z",
    "external_id": null,
    "created_at": "2021-12-07T16:06:49.731705Z"
}

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

12121212

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_br_retail
  • ironbank_br_business

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

Use caseUsernamePasswordUsername TypeUsername 2Password 2API Response
Valid credentialsadv_validpass_valid003validvalid200 Success
Invalid credentialsadv_invalidpass_invalid999invalidinvalid400 Login Error

Additional resources