Sandbox (Aggregation)
Enjoy unlimited testing to speed up your integration with our sandbox environment 🤘.
With Belvo's sandbox environment, you can interact with dummy banking and fiscal 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 and fiscal 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 in100
).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 - Colombia
To test banking institutions that do not require MFA, you can use the following retail institutions:
Erebor Bank
erebor_co_retail
Gringotts Bank
gringotts_co_retail
Gotham Business Bank
gotham_co_business
You can simulate different types of users by using the following login credentials when registering a link:
Username | Password | Use to simulate... | Accounts | Incomes | Owners | Transactions |
---|---|---|---|---|---|---|
bnk100 | full | A user that uses their bank accounts often. | Up to 4* | 1 | 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 |
bnk102 | low | A user that does not use their bank account often. | Up to 2 | None | 1 | Up to 5 |
bnk103 | negative | A user that has overdrawn accounts. | Up to 2 | None | 1 | Up to 5 |
* For Brazillian institutions, we also return a pension fund (previdencia) account.
Banking - Open Finance Brazil
You can test out the consent and data flows for Open Finance Brazil by using the following institution:
ofmockbank_br_retail
For credentials, please see Radiam's Customer Data article.
This is an externally-managed sandbox environment, as such we cannot guarantee the quality of the data nor the uptime of the sandbox institution.
Employment - Mexico
To test employment institutions, you can use the following institution:
Planet Express Employment
planet_mx_employment
You can simulate different types of users by using the following login credentials when registering a link:
Username | Use to simulate... | Owners | Employment Records | Employment Metrics |
---|---|---|---|---|
BLPM951331IONVGR54 | A user with a valid CURP and who has worked in the public system. Note: You can use any valid CURP to simulate this type of user in our sandbox. However, real-world CURPs will generate fake data in our sandbox environment. | 1 * | At least 1 | At least 1 |
Coming soon! | We are working on providing additional logins to simulate different employment use cases. | - | - |
* Note: Some data may be different between our Owners and Employment Records resources in our sandbox environment.
Fiscal - Mexico
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 (returns an empty array) | 1 | None (returns an empty array) | 1 individual tax status |
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 MFA, you can use the following institution:
Heimdall Bank
heimdall_co_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-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:
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 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
Updated about 2 months ago