Pagos con Wealth Reader

Arquitectura en dos pasos

La integración de pagos sigue una estricta separación de responsabilidades en dos pasos:

sequenceDiagram
autonumber
actor Usuario as Usuario
participant Front as Frontend (Comercio)
participant Back as Backend (Comercio)
participant API as API Wealth Reader
participant Widget as Widget Payments
participant Banco as Entidad Bancaria (SCA)
Note over Back,API: Paso previo (solo perfiles administrados)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: catálogo del perfil (institution_code)
Note over Back,API: Paso 1: Creación de la intención inmutable (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 efímero
Note over Front,Widget: Paso 2: Carga y autorización en el widget (Navegador)
Back->>Front: Entrega payment.id y payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) o load-payments.js
Widget->>Usuario: Presenta entidad, importe y concepto inmutables
Usuario->>Widget: Autoriza el pago
Widget->>Banco: Redirección / App to App (SCA)
Banco->>API: Retorno del SCA al callback de Wealth Reader
API-->>Widget: Confirmación técnica de autorización
Note over Back,API: Conciliación y confirmación financiera
loop Hasta estado terminal
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Paso 1 (Backend seguro): Su servidor crea una intención de pago (POST /payments/?action=create) con su X-API-Key, un Idempotency-Key y Content-Type: application/json. En esta llamada se fijan de forma inmutable el importe (amount_minor, en céntimos), la divisa (currency, hoy solo EUR), el beneficiario (beneficiary.name e beneficiary.iban), el concepto del extracto (reference), su referencia interna (customer_reference) y el origen web permitido (allowed_origin). Esos seis campos son obligatorios, y el cuerpo es una lista blanca estricta: cualquier campo no reconocido devuelve 422 invalid_request.
2. Respuesta: 201 con {"success": true, "payment": {…}} — o 200 si se trata de una repetición idempotente. El identificador de la intención viene en payment.id y el token efímero del widget en payment.widget.token.
3. Paso 2 (Frontend del comercio): El navegador monta el widget mediante el script oficial load-payments.js o la función WealthReaderPayments.mount(), entregando únicamente el payment.id y el payment.widget.token. El usuario selecciona su banco (si no se preseleccionó en la intención) y completa la autenticación reforzada (SCA) en la interfaz bancaria.
4. Confirmación financiera: Su backend consulta el estado mediante POST /payments/?action=status, cuyo cuerpo es exactamente {"payment_intent_id": "<id>"}. No hay webhook: se sondea hasta llegar a un estado terminal.

Dos modelos de cobro

Wealth Reader soporta dos modelos según las necesidades del negocio:

1. Integración estándar para comercios (Propio beneficiario):
   • El comercio define libremente el nombre e IBAN del beneficiario, el importe, la divisa (EUR), el concepto y su referencia de pedido.
   • Puede filtrar qué bancos poner a disposición del usuario mediante allowed_institution_codes o permitir todo el catálogo.
2. Perfiles administrados (como cruz_roja_demo):
   • Diseñados para donaciones y demostraciones públicas.
   • El servidor fija las cuentas oficiales de destino para garantizar que los fondos solo puedan dirigirse a la entidad benéfica (por ejemplo, Cruz Roja Española con importes acotados entre 0,01 EUR y 1,00 EUR).

Directorio unificado de entidades bancarias

Wealth Reader proporciona un catálogo unificado de entidades europeas preparadas para iniciación de pagos vía PSD2 a través de:

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

Permite obtener el listado de bancos con sus nombres normalizados, logotipos, métodos de transferencia admitidos y requisitos técnicos (como la necesidad de solicitar el IBAN deudor al pagador). Admite los filtros country, search (alias q), code, payment_method, limit y offset.

Este endpoint es público: no requiere X-API-Key. Enviarla no aporta nada y consume una llamada de la cuota de su credencial.

Use siempre estos códigos tal cual vienen en code. La creación de la intención valida el formato de allowed_institution_codes, pero no comprueba que existan en el catálogo: un código mal escrito no da error al crear y aparece más tarde como un selector de bancos vacío.

Separación de responsabilidades

• La credencial de pagos (X-API-Key) se usa únicamente de servidor a servidor. Jamás debe incluirse en frontend ni en repositorios públicos.
• El navegador recibe únicamente el identificador de la intención y un token efímero de corta duración ligado al origen HTTPS.
• El widget no puede alterar importe, moneda, beneficiario, concepto ni instituciones autorizadas.
• El cierre del modal o widget no sustituye a la consulta de estado financiera en backend.
• Los pagos no comparten credenciales, tokens ni callbacks con el producto de agregación bancaria de Wealth Reader.

Credenciales y cuota

Su credencial de pagos debe tener el producto PAYMENTS habilitado; si no, la API responde 403 payments_not_allowed. Una credencial ausente o con formato incorrecto devuelve 401 invalid_api_key.

Siguiente paso

Continúe con Integración y widget.