Pagaments amb Wealth Reader

Arquitectura en dos passos

La integració de pagaments segueix una separació estricta de responsabilitats en dos passos:

sequenceDiagram
autonumber
actor Usuario as Usuari
participant Front as Frontend (Comerç)
participant Back as Backend (Comerç)
participant API as API Wealth Reader
participant Widget as Widget Payments
participant Banco as Entitat bancària (SCA)
Note over Back,API: Pas previ (només perfils administrats)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Catàleg del perfil (institution_code)
Note over Back,API: Pas 1: Creació de la intenció immutable (Server-to-Server)
Back->>API: POST /payments/?action=create (amb X-API-Key i Idempotency-Key)
API-->>Back: 201 amb payment.id + payment.widget.token efímer
Note over Front,Widget: Pas 2: Càrrega i autorització al widget (Navegador)
Back->>Front: Lliura payment.id i payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) o load-payments.js
Widget->>Usuario: Presenta entitat, import i concepte immutables
Usuario->>Widget: Autoritza el pagament
Widget->>Banco: Redirecció / App to App (SCA)
Banco->>API: Retorn de l'SCA al callback de Wealth Reader
API-->>Widget: Confirmació tècnica de l'autorització
Note over Back,API: Conciliació i confirmació financera
loop Fins a un estat terminal
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Pas 1 (Backend segur): El vostre servidor crea una intenció de pagament (POST /payments/?action=create) amb la seva X-API-Key, un Idempotency-Key i Content-Type: application/json. Aquesta crida fixa de manera immutable l'import (amount_minor, en cèntims), la divisa (currency, actualment només EUR), el beneficiari (beneficiary.name i beneficiary.iban), el concepte de l'extracte (reference), la vostra referència interna (customer_reference) i l'origen web permès (allowed_origin). Aquests sis camps són obligatoris, i el cos és una llista blanca estricta: qualsevol camp no reconegut retorna 422 invalid_request.
2. Resposta: 201 amb {"success": true, "payment": {…}} — o 200 si és una repetició idempotent. L'identificador de la intenció és a payment.id i el token efímer del widget a payment.widget.token.
3. Pas 2 (Frontend del comerç): El navegador munta el widget amb l'script oficial load-payments.js o la funció WealthReaderPayments.mount(), lliurant únicament payment.id i payment.widget.token. L'usuari tria el banc (si no s'ha preseleccionat a la intenció) i completa l'autenticació reforçada (SCA) a la interfície bancària.
4. Confirmació financera: El backend consulta l'estat amb POST /payments/?action=status, amb un cos exactament igual a {"payment_intent_id": "<id>"}. No hi ha webhook: cal consultar periòdicament fins a un estat terminal.

Dos models de cobrament

Wealth Reader admet dos models segons les necessitats del negoci:

1. Integració estàndard per a comerços (beneficiari propi):
   • El comerç defineix lliurement el nom i l'IBAN del beneficiari, l'import, la divisa (EUR), el concepte i la seva referència de comanda.
   • Pot filtrar els bancs disponibles per a l'usuari amb allowed_institution_codes o permetre tot el catàleg.
2. Perfils administrats (com cruz_roja_demo):
   • Dissenyats per a donatius i demostracions públiques.
   • El servidor fixa els comptes oficials de destinació per garantir que els fons només arribin a l'entitat benèfica (per exemple, Creu Roja Espanyola amb imports limitats entre 0,01 EUR i 1,00 EUR).

Directori unificat d'entitats bancàries

Wealth Reader proporciona un catàleg unificat d'entitats europees preparades per a iniciació de pagaments via PSD2 a través de:

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

Permet obtenir els bancs amb noms normalitzats, logotips, mètodes de transferència admesos i requisits tècnics (com haver de demanar l'IBAN deutor al pagador). Admet els filtres country, search (àlies q), code, payment_method, limit i offset.

Aquest endpoint és públic: no requereix X-API-Key. Enviar-la no aporta res i consumeix una crida de la quota de la vostra credencial.

Utilitzeu els codis exactament com apareixen a code. La creació de la intenció valida el format de allowed_institution_codes, però no comprova que existeixin al catàleg: un codi mal escrit no dona error en crear i apareix més tard com un selector de bancs buit.

Separació de responsabilitats

• La credencial de pagaments (X-API-Key) s'utilitza únicament de servidor a servidor. No s'ha d'incloure mai al frontend ni en repositoris públics.
• El navegador només rep l'identificador de la intenció i un token efímer de curta durada vinculat a l'origen HTTPS.
• El widget no pot alterar import, moneda, beneficiari, concepte ni institucions autoritzades.
• Tancar el modal o widget no substitueix la consulta de l'estat financer al backend.
• Els pagaments no comparteixen credencials, tokens ni callbacks amb el producte d'agregació bancària de Wealth Reader.

Credencials i quota

La vostra credencial de pagaments ha de tenir el producte PAYMENTS habilitat; si no, l'API respon 403 payments_not_allowed. Una credencial absent o amb format incorrecte retorna 401 invalid_api_key.

Pas següent

Continueu amb Integració i widget.