1️⃣ Implement the widget

While you're integrating the widget, make sure that:

• Your users first register an account with your application before prompting them to connect their accounts with Belvo.
• You are using the external_id parameter to provide your own unique ID for a link (or group of links) in your system. Note: This parameter is searchable within Belvo's system as well.
• If using single links, you use the fetch_resources parameter to asynchronously receive historical data about your user.
• You can generate an access_token for both individuals and businesses.
• You have correctly implemented your callback URLs.
• You can handle Success, Exit, Error, and Warning events from the Hosted Widget.

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.

📘

For more information on the retry logic you should implement, see our General error handling notes.

3️⃣ Request Handling

Can your integration handle:

• 200, 201, and 202 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 using recurrent links, that you have set up your refresh rate according to your needs (daily, weekly, or monthly) (contact our sales team).
• Only send GET requests after you receive a webhook event.
• Respond within five seconds of receiving a webhook with a 200 OK.
• 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:

• Have a mechanism to avoid duplicate links from being created?
• Monitor for invalid and token_required link statuses, and if needed, prompt your users to update their credentials?
• Familiarized yourself with the Open finance Brazil network limits.

6️⃣ My Belvo Portal

Have you:

• Implemented a easy-to-access link to the My Belvo Portal?
• Implemented a mechanism to handle consent_expired Consent webhook events?

7️⃣ 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, where S are microseconds (from 3 to 6 digits) and Z is either +00:00 or Z.
• 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.

8️⃣ 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.

9️⃣ 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)