Getting started

Integration Flow

Correct path of an iframe integration. The callback is sent before notifying the frontend.

sequenceDiagram
participant Usuario
participant Web
participant Widget as Wealth Reader Widget
participant API as Wealth Reader API
participant Banco as Entidad Financiera
Usuario->>Web: Abre la aplicación
Web->>Widget: Carga el iframe con operation_id
Usuario->>Widget: Elige entidad y da consentimiento
Widget->>API: Solicita los datos con operation_id
API->>Banco: Consulta
Banco-->>API: Responde
API-->>Widget: Devuelve datos normalizados
Widget->>Web: POST al callback (operation_id + token + payload)
Web-->>Widget: HTTP 200 y status ok
Widget-->>Web: postMessage flow completed
Web-->>Usuario: Muestra finalización OK

Who does what

Actor	Responsibility
Your Frontend	Generate a `operation_id` one, load the widget, and listen to `postMessage`.
The Widget	It shows banks, login, 2FA and errors to the user.
The Wealth Reader API	Talk to the entity and normalize the response.
Your Backend	Exposes the callback URL, replies `{"status":"ok"}` and saves `operation_id`, `token` and payload.

If something goes wrong

Incorrect password, 2FA, or an entity error: the widget resolves this with the user. Your front may receive an error JSON for postMessage; the callback is not called until the read finishes successfully.
Your callback does not respond 200 + {"status":"ok"}: the user does not see success and the front does not receive flow completed.
A token cease to be valid (password change, new 2FA): reopen the widget by passing that token one so that the user can reauthenticate.

The detail of each message and the callback body is on the iframe pages.

Next step

If you're integrating by iframe, go through frontend ] and then backend. If you can't embed an iframe, go to OAuth.

Last updated 2026-08-15