Link creation flow

When you're setting up your link creation flow:

1. Make sure you first register your users with your platform.
2. Use the Connect Widget to create your links.
3. Store the received link_id in your database.

👍

Why should you first register a user in your platform and then use the widget?

By first registering your user in your platform, you have a way to associate a user with a created link in your database.

Orphan links

An orphan link is a link that was created but has not been associated with a user in your database.

Orphan links can occur when:

• you do not register your user first with your platform.
• your user closes your application (mobile or browser) during a successful connection process.

To recover orphan links created due to the user closing your application, we recommend using the external_id parameter as an additional identifier for your link in Belvo's database.

Adding your own identifier

You can use the optional external_id parameter when creating a new link to provide an additional unique identifier within the Belvo system. This is particularly useful as you can later make a request to Belvo's Links endpoint and filter for all the links associated to an external_id.

By using external_id and filtering, you can:

• list all the links related to a user.
• get the latest status of each link, and if needed, prompt the user to update their token or their credentials for an institution.
• identify any orphan links for that user and then associate the link_id in your database.

The external_id that you provide:

• should be a unique ID for each user in your database.
• must be at least three characters long.
• can only be composed of letters, numbers, dashes (-), and underscores (_).
• cannot contain any personally identifiable information about the user (email, name, phone number, credit card number, and so on).

🚧

Personally identifiable information with external_id

If you use any personally identifiable information in your external_id, Belvo will set the external_id to null. As such, you will not be able to filter your links by that external_id.

Tips for using external_id

To use the optional external_id parameter, we highly recommend the following flow:

1. Register your users first with your platform and create a unique ID for that user in your database.
2. Use the unique ID as the value of the external_id parameter when creating a link.
3. Use the Connect Widget to create your links.

Then, as required, you can periodically call /links/?external_id={user's unique ID in your system} and identify any orphan links or links that need to have their status updated.

📘

Code examples for starting the widget or filtering responses by external_id

For examples of how to start the widget with the external_id parameter, see our Widget startup configuration article.

For examples of how to filter your response by external_id, see our Filtering responses article.

Avoiding duplicated links

Duplicated links occur when:

• the user tries to connect their account to the same institution with the same credentials a second time.
• you are not storing the link_id in your database.
• the user closes your application (mobile or browser) during a successful connection process.

To help you avoid link duplication, have a look at our helpful tips below.

Tip #1 - Register your users first
Make sure that you register your user with your platform first. This way, you will always have a way to associate created links with a user in your database and keep track of what accounts they have already connected.

Tip #2 - Use external_id

When your user starts a new session on your platform:

1. Request all links associated for the user: /links/?external_id={user's unique ID in your system}.

2. Associate any orphan links that have status=valid with your user in your database and let your user know that the link was created successfully.

If the status of the link is not valid, you can either:

• delete the link and request the user to connect their account again.
• update the status of the link using Widget Update Mode.

This way, you will ensure that you will not have any orphan links and that all the links associated with a user have a valid status.

Tip #3 - Use the widget’s callback metadata

After receiving the Success callback from the widget, you can use the link ID to retrieve information about the link. The information from the link can then be compared to the existing links that this user already created in your database (Tips #1 and #2) and utilize this to detect potential duplicates. For example, you can compare a combination of the account’s institution_id, account name, and account number to determine whether your user has previously linked an account to your application.

Tip #4 - Show already-connected accounts

Before your users open the widget, in your UI, display a list of accounts that they have already connected (to find all the accounts they have, you can use the external_id in combination with the metadata you receive from the Widget in Tip #3). By showing this information, your users will avoid linking the same account again (and you avoid duplicated Links).

Tip #5 - Use institution_user_id to keep track of links

📘

Only applicable for links created after 08-02-2022.

When your user connects their account, we return the institution_user_id, which is a unique 44-character string that can be used to identify a user at a given institution. You can use this identifier to compare in your database whether or not your user has previously connected this account, and if you want to avoid duplicated links, you can choose to replace the existing link.id in your database.

Example:

1. Your user connects their account to an institution and you receive the following link id and institution_user_id:

{
	"id": "link-id-1",
	"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}

2. Your user connects the same account again using the same credentials and you receive:

{
	"id": "link-id-2",
	"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}

3. Comparing the institution_user_id in your database, you see that this is the same account. If you would prefer to not have duplicated links in your database, you can replace the link-id-1 with link-id-2 in your database and use link-id-2 for your future requests.

Opt-in to prevent duplicate links

Belvo offers an opt-in feature designed to prevent duplicated links from being created, ensuring that your users never connect the same account twice to your application. If your user has already successfully connected their account and they try to connect the same account again:

• Integrations using Belvo's Connect Widget - your users will receive an error in the Connect Widget and your backend will receive an Error Event Callback.
• Integrations not using Belvo's Connect Widget - you will receive a 400 duplicated API error.

👍

Links with unconfirmed status

In the situation where your user has previously attempted to create a link but never finished the flow (resulting in the link status being set to unconfirmed), when they try to connect the same account again Belvo will allow for the link to be created.

This feature ensures that you can still retrieve vital user information and provides your users' the ability to still connect their accounts.

If you'd like to opt-in for this feature, just contact our support team and they'll gladly help you out!

📘

In order to use this feature, you may be required to alter your integration to use the external_id parameter on link creation.