Introducción al Hosted Widget

Para aplicaciones nativas móviles y basadas en la web, hemos creado una versión hosted de nuestro widget que simplifica significativamente tu proceso de desarrollo e integración. Todo lo que necesitas es crear un webview en tu aplicación y tener algo de conocimiento sobre el manejo de redirecciones deeplink.

En esta página, te proporcionaremos documentación de referencia sobre qué información pasar al iniciar tu hosted widget, así como los posibles eventos que puedes recibir del widget.

En esta guía te guiaremos a través de:

1. Generar un token de acceso
2. Iniciar el hosted widget
3. Manejar eventos de callback
4. Recuperar datos

Para que el widget aparezca a tus usuarios finales, necesitas generar un access_token en tu servidor y enviarlo a Belvo. Una vez que recibamos la solicitud, recibirás un objeto con dos claves: access y refresh. Pasa el valor de la clave access al iniciar el hosted widget.

Para generar un access_token, simplemente realiza la siguiente llamada desde tu servidor a 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",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENTS", "OWNERS"], 
  "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/",
      "company_terms_version": "2024-03-15"
    },
    "theme": [] // See our dedicated widget customization article
  }
}

Cuando inicias tu webview, para comenzar el widget correctamente, necesitas pasar tu access_token en la cadena de URL.

https://widget.belvo.io/?access_token={access_code}

También puedes pasar los parámetros de configuración, como el idioma del widget (locale), qué tipo de enlace deseas crear (access_mode), o qué instituciones mostrar basadas en los recursos que puedes extraer de ellas (resources), en la URL.

https://widget.belvo.io/
  ?access_token={access_code}
  &locale=pt
  &institutions=inss_br_employment
  &access_mode=recurrent
  &external_id=HJLSI-897809

Para una lista completa de parámetros (junto con detalles de implementación), por favor consulta nuestro artículo de Configuración de Inicio del Widget (Multi-Región).

El hosted widget utiliza redirecciones de deep link para pasar información sobre lo que ocurre en el widget. Necesitarás poder manejar eventos de success, exit y error. La estructura del deep link es:

your-url-here://event_name?parameters

Recibirás un evento success cuando tu usuario haya conectado exitosamente su cuenta a su institución usando el widget. Poder manejar el evento success es crítico ya que contiene el id del enlace del usuario (necesario para posteriormente recuperar datos de la API de Belvo).

your-url-here://success
  ?link={id}}
  &institution={institution_name}

your-url-here://success
  ?link=cb65f82c-dc93-4d3e-8270-9a27528397f5
  &institution=erebor_br_retail

Recibirás un evento exit cuando tu usuario final salga del widget:

• antes de conectar su cuenta.
• después de haber seleccionado una institución.
• debido a un error.

your-url-here://exit
  ?last_encountered_error_code={error_code}
  &last_encountered_error_message={error_message}
  &meta_data_institution_name={institution_name}
  &meta_data_step=abandon-{step_name}


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

El parámetro de consulta last_encountered_error solo se envía si ocurrió un error. Consulta la tabla a continuación para ver una lista completa de posibles códigos de error y sus mensajes.

La cadena de consulta meta_data se envía cada vez que un usuario sale del widget. Consulta la tabla a continuación para ver una lista de posibles valores.

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

Recibirás un evento error cada vez que ocurra un error durante el uso del widget.

your-url-here://error
  ?error={error_name}
  &error_message={error_message}


your-url-here://error
  ?error=ACCESS_TOKEN_NOT_VALID
  &error_message=The%20access%20token%20was%20not%20provided%20or%20is%20not%20valid

Consulta la tabla a continuación para ver una lista de posibles códigos de error y sus mensajes.

Recibirás un evento warning cada vez que ocurra un evento no terminante durante el uso del widget.

your-url-here://warning
  ?warning={warning_code}
  &warning_message={warning_message}

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

Consulta la tabla a continuación para ver una lista de posibles códigos de advertencia y sus mensajes.

Una vez que tu usuario conecte exitosamente su cuenta bancaria, recibirás el link_id en el evento de éxito. Belvo luego te enviará webhooks informándote cuando la información esté lista para el enlace. Para más información, consulta:

• Flujos de Trabajo Asíncronos (Enlaces Únicos)
• Flujos de Trabajo Asíncronos (Enlaces Recurrentes)

Para ayudar en tu desarrollo, hemos creado guías sobre cómo configurar enlaces profundos y escuchar eventos para las siguientes plataformas:

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