Pagamenti con Wealth Reader

Architettura in due passaggi

L'integrazione dei pagamenti segue una rigida separazione delle responsabilità in due fasi:

sequenceDiagram
autonumber
actor Usuario as Utente
participant Front as Frontend (Commercio)
participant Back as Backend (Commercio)
participant API as API Wealth Reader
participant Widget as Pagamenti tramite widget
participant Banco as Banca (SCA)
Note over Back,API: Passaggio precedente (solo profili gestiti)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Catalogo profili (institution_code)
Note over Back,API: Passo 1: Creare l'intento immutabile (Server-to-Server)
Back->>API: POST /payments/?action=create (con X-API-Key e Idempotency-Key)
API-->>Back: 201 con payment.id + payment.widget.token effimero
Note over Front,Widget: Passo 2: Carica e autorizza nel widget (browser)
Back->>Front: Consegna payment.id e payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) o load-payments.js
Widget->>Usuario: Ha un'entità, una quantità e un concetto immutabili
Usuario->>Widget: Autorizzazione del pagamento
Widget->>Banco: Reindirizza / App all'App (SCA)
Banco->>API: Ritorno della SCA al callback di Wealth Reader
API-->>Widget: Conferma tecnica dell'autorizzazione
Note over Back,API: Riconciliazione finanziaria e conferma
loop Fino a uno stato terminale
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Passo 1 (Backend sicuro): Il tuo server crea un'intenzione di pagamento (POST /payments/?action=create) con il tuo X-API-Key, un Idempotency-Key e Content-Type: application/json. In questa chiamata, l'importo (amount_minor, in centesimi), la valuta (currency, oggi solo EUR), il beneficiario (beneficiary.name e beneficiary.iban), la causale dell'estratto conto (reference), il suo riferimento interno (customer_reference) e l'origine web consentita (allowed_origin) sono immutabilmente fissati. Questi sei campi sono obbligatori, e il corpo è una whitelist rigorosa: qualsiasi campo non riconosciuto restituisce 422 invalid_request.
2. Risposta: 201 con {"success": true, "payment": {…}} — oppure 200 per una ripetizione idempotente. L’identificatore dell’intenzione è in payment.id e il token effimero del widget in payment.widget.token.
3. Passo 2 (Frontend del commerciante): Il browser monta il widget usando lo script ufficiale load-payments.js o la funzione WealthReaderPayments.mount(), fornendo solo il payment.id e il payment.widget.token. L'utente seleziona la propria banca (se non era stata pre-selezionata nell'intenzione) e completa l'autenticazione forte (SCA) nell'interfaccia bancaria.
4. Conferma finanziaria: il tuo backend interroga lo stato usando POST /payments/?action=status, il cui corpo è esattamente {"payment_intent_id": "<id>"}. Non ci sono webhook: il backend interroga periodicamente lo stato fino a raggiungere uno stato terminale.

Due modelli di pagamento

Wealth Reader supporta due modelli a seconda delle esigenze dell'azienda:

1. Integrazione standard per i commercianti (beneficiario proprio):
   • Il commerciante definisce liberamente il nome e la IBAN del beneficiario, l'importo, la valuta (EUR), la causale e il riferimento all'ordine.
   • Puoi filtrare quali banche rendere disponibili all'utente tramite allowed_institution_codes oppure consentire l'intero catalogo.
2. Profili gestiti (come cruz_roja_demo):
   • Progettato per donazioni e dimostrazioni pubbliche.
   • Il server imposta i conti ufficiali di destinazione per garantire che i fondi possano essere destinati solo all'ente benefico (ad esempio, la Croce Rossa Spagnola con importi compresi tra 0,01 EUR e 1,00 EUR).

Directorio unificato delle entità bancarie

Wealth Reader fornisce un catalogo unificato degli enti europei preparati per l'avvio dei pagamenti tramite PSD2 tra:

• GET https://api.wealthreader.com/payments/entities/?country=ES

Permette di ottenere l'elenco delle banche con i loro nomi standardizzati, loghi, metodi di trasferimento supportati e requisiti tecnici (come la necessità di richiedere la IBAN del debitore al pagatore). Supporta i filtri country, search (alias q), code, payment_method, limit e offset.

Questo endpoint è pubblico: non richiede X-API-Key. Inviarlo non contribuisce a nulla e consuma una chiamata dalla quota di codice.

Usa sempre i codici esattamente come restituiti in code. La creazione dell’intenzione valida il formato di allowed_institution_codes, ma non verifica che esistano nel catalogo: un codice errato non causa un errore alla creazione, ma produce successivamente un selettore di banche vuoto.

Separazione delle responsabilità

• La chiave di accesso al pagamento (X-API-Key) viene utilizzata solo da server a server. Non deve mai essere inclusa nel frontend o nei repository pubblici.
• Il browser riceve solo l'identificatore dell'intento e un token effimero di breve durata legato all'origine HTTPS.
• Il widget non può modificare l'importo, la valuta, il beneficiario, la causale o le istituzioni autorizzate.
• Chiudere il modale o il widget non sostituisce la consultazione dello stato finanziario del pagamento nel backend.
• I pagamenti non condividono chiavi di accesso, token o callback con il prodotto di aggregazione bancaria di Wealth Reader.

Credenziali e quota

La tua chiave di accesso per i pagamenti deve avere la PAYMENTS del prodotto attivata; in caso contrario, la API risponde 403 payments_not_allowed. Una chiave di accesso mancante o formattata in modo errato restituisce 401 invalid_api_key.

Passo successivo

Continua con Integrazione e widget.