Integration Checklist
To help you out during your integration process, we've created a checklist for you to follow 😉. Please make sure you address all the items before requesting access to the Production environment.
1️⃣ Implement the widget
While you're integrating the widget, make sure that:
- Your users first register an account with your application before accessing Belvo.
- You implement the Success and Exit callback functions.
- You Implement the widget in update mode to handle links with an
invalid
ortoken_required
status. - You use the
institutions.resources
field to define which institutions to display in the widget. - If using single links, you use the
fetch_resources
parameter to asynchronously receive historical data about your user.
We strongly recommend that you follow the flow of first registering your user with your platform and only then using the widget. This way, you avoid any link duplication issues.
2️⃣ Error Handling
Make sure that your integration can handle and log the request_id
of:
- 400 and 401 errors
- 500 Errors
- Timeout errors
We ask you to log the request_id
just in case you need to reach out to our support team. With this ID, we can speed up the troubleshooting process and figure out a solution for you.
3️⃣ Request Handling
Can your integration handle:
- 201 Success responses
- 204 Success responses (when you delete some data)
- Pagination
Additionally, make sure that with successful responses, you store:
- The unique identifier for the object (for example, the
transaction.id
)
This will allow you to avoid having duplicated objects (such as transactions) in your database.
4️⃣ Webhooks
Whether you are using single or recurrent links, make sure you:
- Set a webhook URL in the dashboard so that you can receive webhook events.
- If needed, set a refresh rate of 6, 12, or 24 hours (contact our sales team).
- Only send GET requests after you receive a webhook event.
- Whitelist the following IP addresses:
You can receive webhook events from the following IP addresses:
3.130.254.46
18.220.61.186
18.223.45.212
We highly recommend you whitelist these IP addresses so that you can receive webhook events.
Please remember that you'll need to set different webhook URLs depending on the environment you're working in.
5️⃣ Link creation and management
Does your integration:
- Store the
institution_user_id
when a link is created? (useful to avoid duplicate links). - Monitor for
invalid
andtoken_required
link statuses, and if needed, prompt your users to update their credentials?
6️⃣ Non-breaking changes
If we make the following non-breaking changes to our API, are you sure it won't affect your integration?
- New fields or a different order in the response body.
- Change the number of characters for a string.
- Return
yyyy-MM-ddTHH:mm:ss.SSSZ
timestamps, whereS
are microseconds (from 0 to 6 digits) andZ
is either+00:00
orZ
. For example:2024-03-07T12:57:10Z
2024-07-07T22:40:48.712917Z
- Add new endpoints.
Timestamp change
On 01-03-2022, we will change our timestamps to consistently return only ISO 8601-format timestamps, that is,
2022-02-01T20:25:47.307911Z
.
7️⃣ URL and API Keys
When you are switching to Production, make sure that:
- You are calling the production version of the Belvo API (https://api.belvo.com).
- You are using your Belvo Production API Keys.
- You are storing your API keys securely.
8️⃣ Subscribe to updates
Make sure you've subscribed to the following services to be up to date on the status of our API and institutions:
- Belvo API status
- Institution status (see our dedicated guide)
Updated 3 months ago