Descripción General del Hosted Widget (OFDA)

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.

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

Esta guía te lleva a través de:

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

Para mostrar el widget a tus usuarios finales, genera un token de access en tu servidor y envíalo 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 token de access, simplemente realiza una 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 'ver ejemplos de payloads abajo'

{
  "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://event"
    },
    "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"
        }
      ]
    }
  }
}

{
    "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...",
    "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..."
}

Además de los parámetros configurables a continuación, también puedes agregar personalización y marca adicional a tu widget al generar tu token de access. Para más información, consulta nuestra guía dedicada Marca y personalización (OFDA).

Puedes indicar cuánto tiempo deben almacenarse los datos en la base de datos de Belvo para el link (tanto único como recurrente). Por ejemplo, si envías 90d, Belvo eliminará cualquier dato de su base de datos relacionado con el usuario después de 90 días (es decir, 90 días después de la última vez que se recuperó la información para el usuario). Por defecto, Belvo almacena los datos del usuario durante 365 días, a menos que el link sea eliminado.

Para enlaces únicos y recurrentes, puedes establecer qué recursos Belvo recuperará de manera asincrónica para obtener información histórica utilizando el parámetro fetch_resources. Para más información, consulta nuestra documentación de Flujo de trabajo asincrónico de datos históricos (enlaces únicos).

En el objeto consent, puedes personalizar el mensaje que se muestra a tu usuario sobre para qué caso de uso estás solicitando sus datos en el campo purpose. Por defecto, el widget muestra el siguiente mensaje: _Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito. _.

Para cambiar el contenido, simplemente agrega tu texto (máximo 600 caracteres) al campo purpose:

{
  "widget": {
    "consent": {
       "purpose": "Tu texto personalizado aquí. Máximo 600 caracteres",
       ...
    }
  }   
}

En el objeto widget, necesitas agregar el objeto callback_urls con la siguiente información:

• success es la URL deeplink a la que tu usuario es redirigido cuando el flujo es exitoso.
• exit es la URL deeplink a la que tu usuario es redirigido cuando sale del widget antes de completar el flujo.
• event es la URL deeplink a la que tu usuario es redirigido cuando ocurre un error.

En el objeto consent, necesitas agregar un enlace a los términos y condiciones de tu empresa usando el parámetro terms_and_conditions_url.

En el objeto consent, enviamos una lista predeterminada de recursos para recuperar para el usuario utilizando el parámetro permissions. El valor de permissions debe ser siempre el siguiente array de elementos: ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"].

🚧 Cambio de Permisos de Consentimiento

Si necesitas cambiar los permisos de consentimiento predeterminados, por favor asegúrate de contactar a nuestro equipo de soporte.

En el objeto consent, necesitas proporcionar la información de identificación del usuario para el que deseas recuperar información en el parámetro identification_info. La información que proporciones aquí debe coincidir con la información que la institución regulada tiene para el usuario (por ejemplo, para empresas, el CPF y el nombre deben ser de un usuario con acceso a la cuenta de la empresa). Por ejemplo:

{
  "consent": {
    "identification_info": [
      {
        "type": "CPF",
        "number": "76109277673",
        "name": "Ralph Bragg"
      }
    ]
  }
}

Cuando inicies tu hosted widget, en la cadena de URL necesitas pasar tu:

• token de access generado
• establecer locale a pt

Por ejemplo:

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

También puedes pasar parámetros de configuración adicionales, como el tipo de enlace que deseas crear (access_mode), o qué instituciones mostrar basadas en los recursos que puedes extraer de ellas (resources), en la URL. Para una lista completa de parámetros (junto con detalles de implementación), por favor consulta nuestro artículo de Configuración de Inicio (OFDA) del widget. Por ejemplo:

https://widget.belvo.io/
	?access_token={access_code}
	&locale=pt
	&integration_type=openfinance
	&institution_types=retail
	&institutions=ofbradesco_br_retail
	&country_codes=BR
	&access_mode=recurrent
	&external_id=HJLSI-897809
	&resources=OWNERS,ACCOUNTS

El hosted widget utiliza redirecciones de deep link para transmitir 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

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

Recibirás un evento success cuando tu usuario haya conectado exitosamente su cuenta a su institución utilizando 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.

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 terminal 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=La%20institución%20está%20temporalmente%20no%20disponible.

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

Ahora que puedes manejar enlaces profundos y recuperar el id del enlace desde el evento success, puedes comenzar a recuperar datos sobre tu usuario.

Una vez que tu usuario conecta exitosamente su cuenta bancaria, recibirás el link_id en el evento de éxito. Luego, Belvo 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)