IframePasso 2 di 2

Configura il backend

Ricevete sul vostro server i dati bancari normalizzati e confermate correttamente il callback.

Completate prima la checklist frontend. Il widget non invia i dati bancari via postMessage: li invia qui, con un POST.

Checklist di integrazione

0 di 4

Creare l’URL di callback
Associare dominio, callback e api_key
Provare il flusso con un utente di prova
Memorizzare operation_id, token e statistics.code

1. Creare l’URL di callback

Esponete sul vostro server un endpoint HTTPS che accetti POST con un corpo JSON.

Dopo aver elaborato il necessario, rispondete HTTP 200 con il seguente JSON:

{
    "status": "ok"
}

Se restituite un altro codice di stato o un JSON diverso, il widget non notificherà al frontend che il flusso è terminato correttamente.

Trattate operation_id come idempotente: una consegna ripetuta non deve creare due operazioni nel vostro sistema.

2. Cosa arriva nel POST

Il corpo è lo stesso JSON di POST /entities/ nel riferimento OpenAPI. Campi necessari per collegare l’operazione:

Campo	Uso
`success`	`true` se la lettura è terminata con successo.
`payload`	Dati normalizzati (conti, portafogli, carte, …).
`statistics.operation_id`	L’`operation_id` generato dal vostro frontend.
`statistics.token`	Credenziale custodita per aggiornamenti successivi (se la tokenizzazione è attiva).
`statistics.code`	Codice dell’istituto (`bbva`, `caixabank`, …).
`statistics.SESSION`	Id di sessione, utile in un ticket di supporto.
`statistics.warnings`	Avvisi che non invalidano la lettura (ad esempio un prodotto vuoto).

Esempio abbreviato:

{
    "success": true,
    "payload": {
        "user_information": {
            "ID": "12345678Z",
            "name": "LUIS GARCIA BAQUERO"
        },
        "accounts": [
            {
                "uuid": "8076932f04f73e27fe608fee4d12fca8708dec8c",
                "subtype": "checking",
                "code": "ES4914651234561234567890",
                "name": "Cuenta NOMINA",
                "currency": "EUR",
                "balances": {
                    "available": 14302.07,
                    "current": 14302.07
                },
                "transactions": []
            }
        ]
    },
    "statistics": {
        "SESSION": "A1B2C3D4E5F67890",
        "execution_time": 12.4,
        "warnings": [],
        "operation_id": "8f1c2a6e-4b0d-4c3a-9e21-0d5b7a91c4e2",
        "token": "FRJ0mHlaqZwLzu",
        "code": "bbva"
    }
}

Lo schema completo di payload è nell’OpenAPI. Non date per scontato che ogni chiave sia sempre presente: dipende da product_types e da ciò che l’utente detiene presso l’istituto.

3. Associare dominio, callback e chiave API

Nell’area clienti associate:

il dominio da cui viene caricato il widget (l’origin del vostro frontend);
l’URL di callback appena creato;
la vostra api_key.

Finché il dominio non è registrato, il widget non funziona.

4. Provare il flusso

Aprite la pagina che carica il widget e accedete:

Utente	Password	Risultato
`MOCKDATA`	qualsiasi	Lettura riuscita con dati di esempio anonimizzati. Il callback riceve JSON con `success: true`.
`MOCKOTP`	qualsiasi	Ricrea una challenge di autenticazione a due fattori.
`MOCKLOGINKO`	qualsiasi	Ricrea un errore di login. Il callback non viene chiamato.

Se non avete l’e-mail di benvenuto, richiedetela a support@wealthreader.com.

Se volete ispezionare il POST prima che esista il vostro endpoint, create un URL temporaneo su un servizio come https://pipedream.com/ e impostate quello come callback.

5. Aggiornare i dati (facoltativo)

A questo punto avete un’integrazione one-shot: una lettura ogni volta che l’utente apre il widget.

Se vi serve un batch notturno o un pulsante «Aggiorna», richiamate l’API con il token e il code memorizzati dal callback. Non chiedete di nuovo utente e password.

curl --location 'https://api.wealthreader.com/entities/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=YOUR_API_KEY' \
  --data-urlencode 'code=bbva' \
  --data-urlencode 'token=TOKEN_FROM_CALLBACK' \
  --data-urlencode 'product_types=accounts,portfolios'

Prestate attenzione ai codici di errore: non ritentate una password non valida; potete ritentare quando l’istituto è in manutenzione.

Se il token smette di funzionare (cambio password o nuovo 2FA), riaprite il widget passando quel valore in wr_conf.token così l’utente può riautenticarsi.

Ultimo aggiornamento 2026-08-15