Banking Service

Microservizio per l'integrazione con Enable Banking AIS (Account Information Services).

Implementa il flusso OAuth completo per connettersi ai conti bancari degli utenti tramite il sandbox Enable Banking:

Generazione JWT RS256
Ricerca banche via GET /aspsps
Avvio autorizzazione via POST /auth
Ricezione code sulla callback
Creazione sessione via POST /sessions
Lettura dettagli, saldi e movimenti degli account

Architettura

Frontend Admin
    ↓
Traefik (localhost:8080)
    ↓  PathPrefix(/banking-service)
banking-service (porta 3002)
    ↓
api.enablebanking.com
    ↓
Banca (sandbox o produzione)

Le callback OAuth sono pubbliche (esentate da autenticazione Traefik) perché Enable Banking reindirizza il browser dell'utente senza token:

GET /banking-service/auth/callback
GET /banking-service/callback

Tutte le altre route passano per rainty-auth (forward auth → authService).

Variabili d'ambiente

Variabile	Descrizione
`ENABLE_BANKING_APP_ID`	ID dell'applicazione registrata su enablebanking.com
`ENABLE_BANKING_PRIVATE_KEY_PATH`	Path della chiave RSA privata (in Docker: `/run/secrets/enablebanking_private.key`)
`ENABLE_BANKING_BASE_URL`	Base URL API (default: `https://api.enablebanking.com`)
`ENABLE_BANKING_CALLBACK_URL`	URL pubblico della callback OAuth

Valori per ambiente

Ambiente	`ENABLE_BANKING_CALLBACK_URL`
Locale	`http://localhost:8080/banking-service/auth/callback`
Test	`https://test.rainty.app/banking-service/auth/callback`
Produzione	`https://rainty.app/banking-service/auth/callback`

Chiave privata in Docker

In ambiente Docker la chiave RSA deve essere montata come volume o Docker secret. Il container non include il file — va configurato manualmente.

API Reference

Standard (da BaseService)

Method	Path	Auth	Descrizione
GET	`/banking-service/status/health`	No	Health check
GET	`/banking-service/status/info`	Sì	Info servizio
GET	`/banking-service/release`	No	Versione release
GET	`/banking-service/settings`	Sì	Settings da DB
GET	`/banking-service/dbLogger`	Sì	Stato DB logging

Enable Banking

Method	Path	Auth	Descrizione
GET	`/banking-service/health`	Sì	Health con baseUrl e callbackUrl
GET	`/banking-service/banks`	Sì	Lista banche (`?search=nome\|paese`)
POST	`/banking-service/start-auth`	Sì	Avvia OAuth → restituisce `url` redirect
GET	`/banking-service/auth/callback`	No	Callback OAuth Enable Banking
GET	`/banking-service/callback`	No	Alias callback (compatibilità)
GET	`/banking-service/session/latest`	Sì	Ultima sessione in memoria
GET	`/banking-service/accounts/:id/details`	Sì	Dettagli account
GET	`/banking-service/accounts/:id/balances`	Sì	Saldi account
GET	`/banking-service/accounts/:id/transactions`	Sì	Movimenti (`?date_from=&date_to=&continuation_key=`)
POST	`/banking-service/sync-transactions/:bankAccountId`	Sì	Importa movimenti e aggiorna lo snapshot saldo sul `bank_account`

Flusso end-to-end

1. Cerca una banca

curl -H "Authorization: Bearer <token>" \
  "http://localhost:8080/banking-service/banks?search=UniCredit"

Risposta attesa:

{
  "count": 2,
  "search": "UniCredit",
  "banks": [
    {
      "id": null,
      "name": "UniCredit",
      "country": "IT",
      "bic": null,
      "logo": "https://..."
    }
  ]
}

2. Avvia autorizzazione

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"bankName": "UniCredit", "country": "IT"}' \
  http://localhost:8080/banking-service/start-auth

Risposta attesa:

{
  "authorization_id": "uuid",
  "url": "https://ob.unicredit.eu/...",
  "state": "uuid",
  "redirect_url": "http://localhost:8080/banking-service/auth/callback"
}

3. Apri `url` nel browser

Il browser completa il flusso di consenso bancario e viene reindirizzato alla callback. La pagina di callback conferma:

Enable Banking authorization completed
session_id: uuid
accounts: 2

4. Leggi la sessione

curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/banking-service/session/latest

5. Leggi saldi e movimenti

# Saldi
curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/banking-service/accounts/ACCOUNT_ID/balances

# Movimenti
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8080/banking-service/accounts/ACCOUNT_ID/transactions?date_from=2024-01-01&date_to=2026-12-31"

6. Sincronizza movimenti e saldo del conto rAInty

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"date_from":"2026-01-01","date_to":"2026-05-13"}' \
  http://localhost:8080/banking-service/sync-transactions/BANK_ACCOUNT_ID

Durante questa operazione banking-service importa i movimenti e prova anche a leggere il saldo dal provider. Se un saldo valido è disponibile, aggiorna bank_accounts.current_balance, valuta, timestamp, source e raw snapshot. Il saldo è informativo e viene mostrato dalla UserInterface nel tile del conto bancario.

Per i conti creati manualmente e alimentati via CSV, il provider non esiste: dopo ogni import CSV con nuove transazioni, banking-service ricalcola il saldo come bank_accounts.initial_balance + SUM(bank_transactions.amount) e aggiorna lo stesso snapshot current_balance.

Credenziali sandbox UniCredit

Per testare con UniCredit sandbox non usare credenziali reali. Le credenziali sandbox disponibili sono:

Username	Password
`ituser1bgk`	`pwituser1bgk`
`ituser2bgk`	`pwituser2bgk`
`ituser1corp`	`pwituser1corp`

Fonte: enablebanking.com/docs/api/sandbox

Se il login sandbox restituisce { "authenticated": false } con HTTP 400, il rifiuto avviene nel layer di autenticazione UniCredit sandbox — non nel banking-service.

Troubleshooting

Missing environment variables

{ "error": "Missing environment variables: ENABLE_BANKING_APP_ID, ENABLE_BANKING_PRIVATE_KEY_PATH" }

Verifica che il file .env (locale) o le variabili Docker siano impostate correttamente.

Chiave privata non trovata

Errore al primo utilizzo di /banks o /start-auth. Verifica che ENABLE_BANKING_PRIVATE_KEY_PATH punti al file corretto e che il processo abbia i permessi di lettura.

CORS error dal frontend

Accade quando il banking-service non è in Docker e Traefik non riesce a instradare le richieste. Soluzione: avviare il file provider di Traefik con traefik-conf.d/banking-service-dev.yml che punta a host.docker.internal:3002.

`GET /session/latest` restituisce 404

La callback non è ancora stata completata. Verifica che:

l'URL restituito da /start-auth sia stato aperto nel browser
la redirect URL sia registrata nell'applicazione Enable Banking
la pagina di callback abbia mostrato il successo

Errore callback `error=access_denied`

L'utente ha cancellato il flusso di consenso, oppure la redirect URL non è registrata nell'applicazione Enable Banking.

Redis reconnect loop (sviluppo locale)

Se il servizio gira fuori Docker senza Redis disponibile, il log mostra sub reconnecting in loop. Il servizio funziona comunque per le chiamate API. Per eliminare il loop avviare Redis:

docker compose --env-file docker/.env.dev -f docker/docker-compose.dev.yml up -d redis

Note implementative

Le sessioni sono in memoria: un riavvio del servizio cancella latestAuthorization e latestSession.
JWT RS256 con scadenza 1 ora, rigenerato a ogni chiamata API verso Enable Banking.
PSU headers (Psu-Ip-Address, Psu-User-Agent, ecc.) vengono propagati automaticamente alle chiamate account se presenti nella request in arrivo.

Architettura​

Variabili d'ambiente​

Valori per ambiente​

API Reference​

Standard (da BaseService)​

Enable Banking​

Flusso end-to-end​

1. Cerca una banca​

2. Avvia autorizzazione​

3. Apri url nel browser​

4. Leggi la sessione​

5. Leggi saldi e movimenti​

6. Sincronizza movimenti e saldo del conto rAInty​

Credenziali sandbox UniCredit​

Troubleshooting​

Missing environment variables​

Chiave privata non trovata​

CORS error dal frontend​

GET /session/latest restituisce 404​

Errore callback error=access_denied​

Redis reconnect loop (sviluppo locale)​

Note implementative​