Hosted Widget (OFDA)
For mobile-native applications, we've created a hosted version of our widget that significantly simplifies your development and integration process. All it requires is for you to create a webview in your application and some knowledge of handling deeplink redirects.
On this page, we'll provide you with reference documentation on what information to pass when starting your hosted widget as well as the possible events you can receive from the widget.
In this guide we’ll walk you through:
- Generating an access token
- Starting the hosted widget
- Handling callback events
- Retrieving data
For mobile-native applications, we have developed a specialized App2App flow that improves the user experience when they are connecting their account within your application. For more details, check out our Hosted Widget App2App Flow for OFDA.
1. Generating an access_token (OFDA)
For the widget to appear to your end users, you need to generate an access_token
in your server-side and send it to Belvo. Once we receive the request, you'll receive an object with two keys: access
and refresh
. Pass the value of the access
key when starting the hosted widget.
The returned values are valid for 10 minutes and we invalidate the token as soon as a user successfully connects their account.
To generate an access_token
, simply make a call from your server-side to Belvo:
curl -X POST \
https://sandbox.belvo.com/api/token/ \
-H 'Content-Type: application/json' \
-H 'Host: sandbox.belvo.com' \
-d 'see example payloads below'
{
"id": "YOUR_SECRET_ID",
"password": "YOUR_SECRET_PASSWORD",
"scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
"stale_in": "300d",
"fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
"widget": {
"purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
"openfinance_feature": "consent_link_creation",
"callback_urls": {
"success": "your_deeplink_here://success",
"exit": "your_deeplink_here://exit",
"event": "your_deeplink_here://error"
},
"consent": {
"terms_and_conditions_url": "https://www.your_terms_and_conditions.com",
"permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS","CREDIT_OPERATIONS"],
"identification_info": [
{
"type": "CPF",
"number": "76109277673",
"name": "Ralph Bragg"
}
]
}
}
}
{
"id": "YOUR_SECRET_ID",
"password": "YOUR_SECRET_PASSWORD",
"scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
"stale_in": "300d",
"fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
"widget": {
"purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
"openfinance_feature": "consent_link_creation",
"callback_urls": {
"success": "your-deeplink-here://success",
"exit": "your-deeplink-here://exit",
"event": "your-deeplink-here://error"
},
"consent": {
"terms_and_conditions_url": "https://www.belvo.com",
"permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"
],
"identification_info": [
{
"type": "CPF",
"number": "76109277673",
"name": "Ralph Bragg"
},
{
"type": "CNPJ",
"number": "50685362006773",
"name": "Belvo OF test"
}
]
}
}
}
{
"refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU3YzBmNyIsInVzZXJfaWQiOiI2ZTliZTg4NC00NzgxLTQxNDMtYjY3My1hY2EwMjQ3NWVlOGMiLCJvcmdhbml6YXRpb25fbmFtZSI6IkRvbWluaWsgQ2hvbGV3c2tpJ3MgdGVhbSIsIm9yZ2FuaXphdGlvbl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsInNjb3BlcyI6WyJyZWFkX2luc3RpdHV0aW9ucyIsIndyaXRlX2xpbmtzIl0sImVudmlyb25tZW50Ijoic2FuZGJveCIsImFwaV91cmwiOiJzYW5kYm94LmJlbHZvLmNvbSIsImNyZWRlbnRpYWxzX3N0b3JhZ2UiOiIzMGQiLCJzdGFsZV9pbiI6IjM2NWQiLCJmZXRjaF9yZXNvdXJjZXMiOlsiQUNDT1VOVFMiLCJUUkFOU0FDVElPTlMiLCJPV05FUlMiXSwiaXNzIjoic2FuZGJveC5iZWx2by5jb20ifQ.X43VAc6c37U0JbiYgSd_r4SESjvGOuMgOpK5_DbuMHF7seATr7atO1QiUGwxdwBlEHo9ECST_9QKiHjv7G2czg",
"access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhhMjNhIiwidXNlcl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsIm9yZ2FuaXphdGlvbl9uYW1lIjoiRG9taW5payBDaG9sZXdza2kncyB0ZWFtIiwib3JnYW5pemF0aW9uX2lkIjoiNmU5YmU4ODQtNDc4MS00MTQzLWI2NzMtYWNhMDI0NzVlZThjIiwic2NvcGVzIjpbInJlYWRfaW5zdGl0dXRpb25zIiwid3JpdGVfbGlua3MiXSwiZW52aXJvbm1lbnQiOiJzYW5kYm94IiwiYXBpX3VybCI6InNhbmRib3guYmVsdm8uY29tIiwiY3JlZGVudGlhbHNfc3RvcmFnZSI6IjMwZCIsInN0YWxlX2luIjoiMzY1ZCIsImZldGNoX3Jlc291cmNlcyI6WyJBQ0NPVU5UUyIsIlRSQU5TQUNUSU9OUyIsIk9XTkVSUyJdLCJpc3MiOiJzYW5kYm94LmJlbHZvLmNvbSJ9.2Irt1KCEKo6V17Y-N3zWeX3AchEvCrUWa_AlWoZ2gIIBhHvghHGkXtupOOrXKVqW9kTCOBE77-1riyyblUo4fw"
}
Configurable parameters
Add additional branding to your widget
In addition to the required configurable parameter below, you can also add additional branding and customization to your widget when generating your
access_token
. For more information, see our dedicated Branding and customization (OFDA) guide.
stale_in
You can indicate how long any data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through 90d, Belvo will remove any data from its database relating to the user after 90 days. By default Belvo stores user data for 365 days, unless the link is deleted.
Belvo will only remove data for links that have not been updated in the period you provide in
stale_in
.For example, if you set
stale_in
to 42d and only request information once on that day, then Belvo will remove any data associated with the link after 42 days. However, if you make another request five days later, then Belvo will restart the day counter to that day.
fetch_resources
For single links, you can set which resources Belvo will asynchronously retrieve historical information for using the fetch_resources
parameter. For more information, see our Asynchronous historical data workflow (single links) documentation.
To use
fetch_resources
for single links, you must have webhooks set up.
Resource | Institution Type |
---|---|
ACCOUNTS | Banking |
OWNERS | Banking |
TRANSACTIONS | Banking |
BILLS | Banking (OFDA only) |
INVOICES | Fiscal |
TAX_COMPLIANCE_STATUS | Fiscal |
TAX_RETENTIONS | Fiscal |
TAX_STATUS | Fiscal |
OWNERS | Employment |
EMPLOYMENT_RECORDS | Employment (Mexico only) |
EMPLOYMENT_METRICS | Employment (Mexico only) |
EMPLOYMENT_SCORES | Employment (Mexico only) |
EMPLOYMENTS | Employment (Brazil only) |
purpose
In the consent
object, you can customize the messaging that is displayed to your user regarding for what use case you are requesting their data for in the purpose
field. By default, the widget displays the following message: Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito. .
To change the content, just add your text (maximum 600 characters) to the purpose
field:
{
"widget": {
"consent": {
"purpose": "Your custom text here. Max 600 characters",
...
}
}
}
callback_urls
In the widget
object, you need to add the callback_urls
object with the following information:
success
is the deeplink URL your user is redirected to when the flow is successful.exit
is the deeplink URL your user is redirected to when they exit the widget before completing the flow.event
is the deeplink URL your user is redirected to when an error occurs.
terms_and_conditions_url
In the consent
object, you need to add a link to the terms and conditions of your company using the terms_and_conditions_url
parameter.
identification_info
In the consent
object, you need to provide the identification information of the user that you want to retrieve information for in the identification_info
parameter. The information that you provide here must match the information that the regulated institution has for the user (for example, for businesses, the CPF and name must be for a user with access to the business account). For example:
{
"consent": {
"identification_info": [
{
"type": "CPF",
"number": "76109277673",
"name": "Ralph Bragg"
}
]
}
}
{
"consent": {
"identification_info": [
{
"type": "CPF",
"number": "76109277673",
"name": "Ralph Bragg"
},
{
"type": "CNPJ",
"number": "50685362006773",
"name": "Belvo OF test"
}
]
}
}
✳️ OK! Now that you can generate access_token
, you can start the widget!
2. Starting the widget (OFDA)
When you initiate your hosted widget, in the URL string you need to pass your:
- generated
access_token
- set
locale
topt
- set
mode
towebapp
For example:
https://widget.belvo.io/?access_token={access_code}&locale=pt&mode=webapp
You can also pass additional configuration parameters, such as what kind of link you want to create (access_mode
), or what institutions to display based on the resources you can extract from them (resources
), in the URL. For a full list of parameters (along with implementation details), please see our widget Startup Configuration (OFDA) article. For example:
https://widget.belvo.io/
?access_token={access_code}
&locale=pt
&mode=webapp
&integration_type=openfinance
&institution_types=retail
&institutions=ofbradesco_br_retail
&country_codes=BR
&access_mode=recurrent
&external_id=HJLSI-897809
&resources=OWNERS,ACCOUNTS
3. Handling callback events
The hosted widget makes use of deep link redirects to pass information about what happens in the widget. You'll need to be able to handle success, exit, and error events. The structure of the deep link is:
Platform guides
To aid your development, we've created guides on how to set up deep links and listen for events for the following platforms:
Success event
You'll receive a success
event when your user has successfully connected their account to their institution using the widget. Being able to handle the success
event is critical as it contains the link id
of the user (required to later retrieve data from the Belvo API).
Parameter | Description |
---|---|
link | The link ID for the user. You'll need this ID to be able to make further requests for the user. |
institution | The institution that the link was created with. |
your-url-here://success
?link=cb65f82c-dc93-4d3e-8270-9a27528397f5
&institution=erebor_br_retail
Exit event
You'll receive an exit
event when your end user exits the widget:
- before connecting their account.
- after they have selected an institution.
- due to an error.
last_encountered_error
The last_encountered_error
query string is only sent if an error occurred. See the table below for a full list of possible error codes and their messages.
Error code | Error message |
---|---|
institution_down | The financial institution is down, try again later |
login_error | The possible error messages for a login_error are: - Invalid credentials provided to login to the institution - The user account is locked, user needs to contact the institution to unlock it - The user account access was forbidden by the institution - Impossible to login, something unexpected happened while logging into the institution. Try again later. |
too_many_sessions | Impossible to login, a session is already opened with the institution for these credentials |
unexpected_error | Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution |
meta_data
The meta_data
query string is sent whenever a user exits the widget. See the table below for a list of possible values.
Parameter | Description |
---|---|
step | Sent when the user exits the widget at the initial screen. The value of the parameter is always abandon-survey . |
institution_name | Sent when the user exits the widget after selecting an institution. The value will be Belvo's institution code, for example banamex_mx_retail . |
your-url-here://exit
?last_encountered_error_code=login_error
&last_encountered_error_message=Invalid%20credentials%20provided%20to%20login%20to%20the%20institution
&meta_data_institution_name=amex_mx_retail
&meta_data_step=abandon-survey
Error event
You'll receive an error
event whenever an error occurs during the use of the widget.
See the table below for a list of possible error codes and their messages.
Error code | Error message |
---|---|
ACCESS_TOKEN_NOT_VALID | The access token was not provided or is not valid |
your-url-here://exit
?error=ACCESS_TOKEN_NOT_VALID
&error_message=The%20access%20token%20was%20not%20provided%20or%20is%20not%20valid
Warning event
You'll receive a warning
event whenever a non-terminating event occurs during the use of the widget.
See the table below for a list of possible warning codes and their messages.
Warning code | Warning message |
---|---|
institution_disabled | The institution is temporarily unavailable. |
your-url-here://warning
?warning=institution_disabled
&warning_message=The%20institution%20is%20temporarily%20unavailable.
Now that you can handle deep links (most importantly to retrieve the link id
from the success
event), you will be able to start retrieving data about your user.
4. Retrieving data
Once your user successfully connects their bank account, you'll receive the link_id
in the success event. Belvo will then send you webhooks informing you when information is ready for the link. For more information, see:
Updated 3 months ago