Integrazione dei pagamenti e widget

La chiave API (X-API-Key) non dovrebbe mai apparire in HTML, JavaScript client, log del browser o parametri URL.

1. Elenco delle entità bancarie

Per scoprire quali banche sono disponibili e ottenere i loro loghi, nomi e requisiti, puoi controllare direttamente l'endpoint dell'entità dal suo backend. Ogni entità ha due loghi: logo, quello che Wealth Reader consigliato di mostrare (il proprio logo vettoriale quando esiste, il logo del fornitore altrimenti, secondo logo_source), e logo_fallback, quello del fornitore, così che la sua interfaccia possa usarlo se il primo non si carica:

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

Questo endpoint è pubblico: non inviare X-API-Key. Farlo non cambia la risposta, consuma una chiamata dalla tua quota e, se i pagamenti fossero disabilitati sul tuo account, convertirebbe una query funzionante in un 503.

Supporta anche parametri di query opzionali:

• country: codice ISO a due lettere (ad esempio ES, FR, DE, IT, PT...). Con ALL o vuoto non viene filtrato per paese.
• search (alias q): ricerca testuale per nome o codice (ad esempio santander, bbva).
• code- Recupera un'entità specifica tramite il suo codice esatto.
• payment_method: Filtra per metodo supportato (ad esempio sepa_credit_transfer).
• limit e offset: paginazione dei risultati.

Risposta breve di esempio:

{
  "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
    }
  ]
}

Modello consigliato per mostrare il logo con supporto automatico:

<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; }">

In /payments/entities/ entrambi i campi sono sempre presenti e sono null quando non c'è un logo. Le istituzioni POST /payments/?action=profile-institutions e widget portano gli stessi logo e logo_fallback come campi opzionali: mancano quando non c'è un logo utilizzabile. I loghi puntano solo a cdn.wealthreader.com o assets.exthand.com; se la tua pagina ha CSP, aggiungi entrambi gli host a img-src.

Profili gestiti (come la demo di donazioni): Se utilizzi un profilo preconfigurato come cruz_roja_demo, consulta le istituzioni e le condizioni fissate dal server chiamando POST /payments/?action=profile-institutions con il corpo {"profile": "cruz_roja_demo"}.

2. Creare un'intento di pagamento nel backend

Quando il cliente decide di pagare al momento del pagamento, il server genera una chiave di idempotenza unica e richiede la creazione immutabile del pagamento al API di Wealth Reader.

Modello standard per i commercianti (Beneficiario proprio)

Il commerciante specifica il suo conto di recupero, l'importo in centesimi (amount_minor), il riferimento al pagamento e l'origine web dove il widget si caricherà:

: "${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 è opzionale. Se omesso, l'utente potrà scegliere tra tutte le entità presenti nel catalogo.

Modello con Profilo Gestito (Dimostrazione di Donazione)

Se integri il profilo gestito 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"
  }'

Risposta del API

Il API risponde confermando l'intento immutabile e consegnando i dati per inizializzare il 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"
    }
  }
}

Il tuo backend dovrebbe fornire al browser dell'utente solo il payment.id e il payment.widget.token.

3. Monta il widget nel frontend

Ci sono due modi per montare il widget nella tua interfaccia web: usando lo script dichiarativo ufficiale oppure usando il API JavaScript programmatico.

Opzione A: tramite script dichiarativo (load-payments.js)

Incorpora il contenitore e il script di caricamento nella tua pagina di checkout:

<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>

Opzione B: tramite JavaScript API (WealthReaderPayments.mount)

Se usi framework come React, Vue, Angular o un flusso 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'
});

Il widget ottiene la configurazione direttamente dai server Wealth Reader con il token utilizzabile solo una volta. Se la banca richiede l'identificazione del conto di debito prima di reindirizzare, il widget richiede il IBAN di addebito direttamente al pagatore senza che il commerciante debba elaborarla.

Eventi principali del widget

Passo successivo

Recensione Intenzioni e idempotenza.