Integració de pagaments i widgets

La clau API (X-API-Key) mai no hauria d'aparèixer en HTML, JavaScript del client, registres del navegador o paràmetres d'URL.

1. Directori d'entitats bancàries

Per saber quins bancs estan disponibles i obtenir els seus logotips, noms i requisits, pots comprovar l'endpoint de l'entitat directament des del seu backend. Cada entitat ve amb dos logotips: logo, el que Wealth Reader recomana mostrar (el seu propi logotip vectorial quan existeix, el logotip del proveïdor, segons logo_source), i logo_fallback, el del proveïdor, perquè la seva interfície el pugui utilitzar si el primer no es carrega:

curl --request GET 'https://api.wealthreader.com/payments/entities/?country=ES'

Aquest punt final és públic: no enviïs X-API-Key. Fer-ho no canvia la resposta, consumeix una trucada de la teva quota, i si els pagaments estiguessin desactivats al teu compte, convertiria una consulta funcional en una 503.

També admet paràmetres de consulta opcionals:

• country: Codi ISO de dues lletres (per exemple, ES, FR, DE, IT, PT...). Amb ALL o buit no es filtra per país.
• search (àlies q): cerca textual per nom o codi (per exemple, santander, bbva).
• code- Recupera una entitat específica pel seu codi exacte.
• payment_method: Filtra per mètode suportat (per exemple, sepa_credit_transfer).
• limit i offset: paginació dels resultats.

Exemple de resposta curta:

{
  "success": true,
  "total": 2,
  "entities": [
    {
      "code": "santander-es",
      "name": "Banco Santander",
      "country": "ES",
      "logo": "https://cdn.wealthreader.com/santander.svg",
      "logo_fallback": "https://assets.exthand.com/bsdk/banks/logos/ES/santander.svg",
      "logo_source": "wealthreader",
      "payment_methods": ["sepa_credit_transfer", "instant_sepa_credit_transfer"],
      "requires_debtor_iban": true
    },
    {
      "code": "bbva-es",
      "name": "BBVA",
      "country": "ES",
      "logo": "https://cdn.wealthreader.com/bbva.svg",
      "logo_fallback": "https://assets.exthand.com/bsdk/banks/logos/PT/bbva.svg",
      "logo_source": "wealthreader",
      "payment_methods": ["sepa_credit_transfer", "instant_sepa_credit_transfer"],
      "requires_debtor_iban": false
    }
  ]
}

Patró recomanat per mostrar el logotip amb suport automàtic:

<img src="https://cdn.wealthreader.com/santander.svg"
     data-fallback="https://assets.exthand.com/bsdk/banks/logos/ES/santander.svg"
     alt="Banco Santander" width="160" height="48"
     onerror="if (this.dataset.fallback && this.src !== this.dataset.fallback) { this.src = this.dataset.fallback; } else { this.hidden = true; }">

En /payments/entities/ ambdós camps sempre estan presents i es null quan no hi ha logotip. Les institucions de POST /payments/?action=profile-institutions i widgets porten els mateixos logo i logo_fallback com a camps opcionals: falten quan no hi ha cap logotip utilitzable. Els logotips només apunten a cdn.wealthreader.com o assets.exthand.com; si la teva pàgina té CSP, afegeix ambdós hosts a img-src.

Perfils gestionats (com la demo de donació): Si utilitzeu un perfil preconfigurat com cruz_roja_demo, consulteu les institucions i condicions establertes pel servidor cridant- POST /payments/?action=profile-institutions amb el cos {"profile": "cruz_roja_demo"}.

2. Crear una intenció de pagament al backend

Quan el client decideix pagar a la caixa, el seu servidor genera una clau d'idempotència única i sol·licita la creació immutable del pagament al API de Wealth Reader.

Model estàndard per a comerciants (beneficiari propi)

El comerciant especifica el seu compte de cobrament, l'import en cèntims (amount_minor), la referència de pagament i l'origen web on es carregarà el widget:

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere una clave UUID v4 o de alta entropía para este intento}"

curl --request POST 'https://api.wealthreader.com/payments/?action=create' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount_minor": 1500,
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido #78901",
    "customer_reference": "pedido-78901",
    "allowed_origin": "https://tienda.example.com",
    "allowed_institution_codes": ["santander-es", "bbva-es", "caixabank-es", "sabadell-es"],
    "locale": "es"
  }'

Nota: allowed_institution_codes és opcional. Si s'omet, l'usuari podrà triar entre totes les entitats del catàleg.

Model amb Perfil Gestionat (Demostració de Donació)

Si integres el perfil gestionat cruz_roja_demo:

curl --request POST 'https://api.wealthreader.com/payments/?action=create' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "profile": "cruz_roja_demo",
    "institution_code": "santander-es",
    "amount_minor": 100,
    "customer_reference": "donativo-demo-0042",
    "allowed_origin": "https://tienda.example.com",
    "locale": "es",
    "expected_mode": "live"
  }'

Resposta de la API

El API respon confirmant la intenció immutable i lliurant les dades per inicialitzar el widget:

{
  "success": true,
  "payment": {
    "id": "11111111-1111-4111-8111-111111111111",
    "amount_minor": 1500,
    "currency": "EUR",
    "state": "ready",
    "interaction_status": "not_started",
    "payment_status": "not_initiated",
    "payment_attestation": {
      "mode": "live",
      "provider_binding": "PROVIDER_BINDING"
    },
    "widget": {
      "url": "https://widget.wealthreader.com/payments/",
      "token": "SHORT_LIVED_WIDGET_TOKEN",
      "expires_at": "2026-09-04T15:30:00+00:00"
    }
  }
}

El teu backend hauria de lliurar al navegador de l'usuari només la payment.id i la payment.widget.token.

3. Munta el widget a la interfície

Hi ha dues maneres de muntar el widget a la teva interfície web: utilitzar l'script declaratiu oficial o utilitzar el API programàtic JavaScript.

Opció A: mitjançant script declaratiu (load-payments.js)

Incrusta el recipient i el carregador a la teva pàgina de pagament:

<div id="wr-payment-container"></div>

<script>
  document.querySelector('#wr-payment-container').addEventListener(
    'wealthreader:payment',
    (event) => {
      console.log('Evento de pago recibido:', event.detail.type, event.detail);

      if (event.detail.type === 'payment_status') {
        console.log('Estado actual:', event.detail.status);
      }

      if (event.detail.type === 'flow_closed') {
        // La interacción del usuario ha finalizado.
        // Consulte el estado financiero definitivo desde su backend.
      }
    }
  );
</script>

<script
  src="https://widget.wealthreader.com/js/load-payments.js"
  data-target="#wr-payment-container"
  data-payment-intent-id="11111111-1111-4111-8111-111111111111"
  data-widget-token="SHORT_LIVED_WIDGET_TOKEN"
  data-locale="es">
</script>

Opció B: mitjançant JavaScript API (WealthReaderPayments.mount)

Si utilitzes frameworks com React, Vue, Angular o un flux SPA:

import { useEffect, useRef } from 'react';

// Cargue previamente https://widget.wealthreader.com/js/load-payments.js
const target = document.getElementById('wr-payment-container');

// Los eventos llegan como CustomEvent del DOM sobre el propio contenedor.
target.addEventListener('wealthreader:payment', (event) => {
  const detail = event.detail;
  if (detail.type === 'payment_status') {
    console.log('Estado del pago:', detail.status);
  }
  if (detail.type === 'flow_closed') {
    // Notificar al backend para comprobar la liquidación
  }
});

window.WealthReaderPayments.mount({
  target: target,
  paymentIntentId: '11111111-1111-4111-8111-111111111111',
  widgetToken: 'SHORT_LIVED_WIDGET_TOKEN',
  locale: 'es'
});

El widget obté la configuració directament dels servidors Wealth Reader amb el token d'un sol ús. Si el banc requereix que el compte de dèbit sigui identificat abans de redirigir, el widget sol·licita el IBAN directament al pagador sense que el comerciant hagi de processar-lo.

Esdeveniments principals de Widget

Següent pas

Ressenya Intencions i idempotència.