# Hosted Widget Introduction

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:

1. Generating an access token
2. Starting the hosted widget
3. Handling callback events
4. Retrieving data


br
## Generating an access_token

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 the following call from your server-side to Belvo:

Employments Brazil

```shell
curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d 'see example payloads below'
```

Employments Brazil
{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENTS", "OWNERS"], // [!code highlight]
  "widget": {
    "callback_urls": {
      "success": "your_deeplink_here://success",
      "exit": "your_deeplink_here://exit",
      "event": "your_deeplink_here://error"
    },
    "branding": {
      "company_icon": "https://mysite.com/icon.svg",
      "company_logo": "https://mysite.com/logo.svg",
      "company_name": "ACME",
      "company_terms_url": "https://belvo.com/terms-service/"
    },
    "theme": [] // See our dedicated widget customization article
  }
}

Employment Records Mexico

```shell
curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d 'see example payloads below'
```

Employment Records Mexico
{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"], // [!code highlight]
  "widget": {
    "callback_urls": {
      "success": "your-url-here://success",
      "exit": "your-url-here://exit",
      "event": "your-url-here://error"
    },
    "branding": {
      "company_icon": "https://mysite.com/icon.svg",
      "company_logo": "https://mysite.com/logo.svg",
      "company_name": "ACME",
      "company_terms_url": "https://belvo.com/terms-service/"
    },
    "theme": [] // See our dedicated widget customization article
  }
}
Fiscal Mexico

```shell
curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d 'see example payloads below'
```

Fiscal Mexico
{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": [ // [!code highlight]
    "FINANCIAL_STATEMENTS",
    "INVOICES",
    "TAX_RETURNS",
    "TAX_RETENTIONS",
    "TAX_STATUS",
    "TAX_COMPLIANCE_STATUS"
  ],
  "widget": {
    "callback_urls": {
      "success": "your-url-here://success",
      "exit": "your-url-here://exit",
      "event": "your-url-here://error"
    },
    "branding": {
      "company_icon": "https://mysite.com/icon.svg",
      "company_logo": "https://mysite.com/logo.svg",
      "company_name": "ACME",
      "company_terms_url": "https://belvo.com/terms-service/"
    },
    "theme": [] // See our dedicated widget customization article
  }
}

br
## Starting the widget

When you initiate your webview, in order to start the widget correctly, you need to pass your `access_token` in the URL string.

You can also pass the configuration parameters, such as the language of the widget (`locale`), 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.

Employments Brazil Example

```markup Employments Brazil Startup Configuration Example
https://widget.belvo.io/
  ?access_token={access_code}
  &locale=pt
  &institutions=inss_br_employment
  &access_mode=recurrent
  &external_id=HJLSI-897809
```

Employment Records Mexico Example

```markup Employment Records Mexico Startup Configuration Example
https://widget.belvo.io/
  ?access_token={access_code}
  &locale=es
  &institutions=imss_mx_employment,issste_mx_employment
  &access_mode=recurrent
  &external_id=HJLSI-897809
```

Fiscal Mexico Example

```markup Fiscal Mexico Startup Configuration Example
https://widget.belvo.io/
  ?access_token={access_code}
  &locale=es
  &institutions=sat_mx_fiscal
  &access_mode=recurrent
  &external_id=HJLSI-897809
```

For a full list of parameters (along with implementation details), please see our widget **Startup Configuration (Multi-Region) article**.

## Handling callback events

We make use of deep link redirects in order to pass information about what happens in the widget. The structure of our deep links is:

You'll need to be able to handle **success**, **exit**, and **error** events.

### 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
```

br
### 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.


br
#### 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`. |



```markup Exit Event Example
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
```

br
### 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 |



```markup Error Event Example
your-url-here://exit
  ?error=ACCESS_TOKEN_NOT_VALID
  &error_message=The%20access%20token%20was%20not%20provided%20or%20is%20not%20valid
```

br
br
### 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. |



```markup Warning Event Example
your-url-here://warning
  ?warning=institution_disabled
  &warning_message=The%20institution%20is%20temporarily%20unavailable.
```

br
## 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:

- Asynchronous Workflows (Single Links)
- Asynchronous Workflows (Recurrent Links)


br
## 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:

- iOS (Swift)
- Android (Kotlin)
- React Native