Zahlungsintegration & Widget

Der API -Schlüssel (X-API-Key) darf niemals in HTML, Client-JavaScript, Browserprotokollen oder URL-Parametern erscheinen.

1. Verzeichnis der Bankeinrichtungen

Um herauszufinden, welche Banken verfügbar sind und deren Logos, Namen und Anforderungen zu erhalten, können Sie den Endpunkt der Entität direkt vom Backend aus überprüfen. Jede Entität hat zwei Logos: logo, das empfohlen Wealth Reader anzuzeigen (ihr eigenes Vektorlogo, wenn es existiert, ansonsten das des Anbieters, laut logo_source), und logo_fallback, das des Anbieters, damit seine Schnittstelle es nutzen kann, falls das erste nicht geladen wird:

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

Dieser Endpunkt ist öffentlich: X-API-Keynicht senden. Dadurch ändert sich die Antwort nicht, er verbraucht einen Anruf von Ihrer Quote, und wenn Zahlungen in Ihrem Konto deaktiviert würden, würde eine funktionierende Abfrage in eine 503umgewandelt werden.

Es unterstützt außerdem optionale Abfrageparameter:

• country: ISO-Zweibuchstab-Code (z. B. ES, FR, DE, IT, PT...). Mit ALL oder leer wird er nicht nach Land gefiltert.
• search (Alias q): Textsuche nach Namen oder Code (z. B. santander, bbva).
• code- Ruft eine bestimmte Entität durch ihren exakten Code ab.
• payment_method: Filtert nach unterstützter Methode (z. B. sepa_credit_transfer).
• limit und offset: Paginierung der Ergebnisse.

Eine kurze Antwort:

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

Empfohlenes Muster zur Darstellung des Logos mit automatischem Fallback:

<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/ sind beide Felder immer vorhanden und null , wenn kein Logo vorhanden ist. Die POST /payments/?action=profile-institutions - und Widget-Institutionen tragen dieselben logo und logo_fallback wie optionale Felder: Sie fehlen, wenn kein brauchbares Logo vorhanden ist. Logos verweisen nur auf cdn.wealthreader.com oder assets.exthand.com; wenn Ihre Seite CSP hat, fügen Sie beide Hosts zu img-srchinzu.

Verwaltete Profile (wie die Spendendemo): Wenn Sie ein vorkonfiguriertes Profil wie cruz_roja_demoverwenden, fragen Sie die vom Server festgelegten Institutionen und Bedingungen ab, indem Sie POST /payments/?action=profile-institutions mit dem {"profile": "cruz_roja_demo"}Body aufrufen.

2. Erstelle eine Zahlungsabsicht im Backend

Wenn der Kunde sich entscheidet, an seiner Kasse zu bezahlen, generiert sein Server einen einzigartigen Idempotenzschlüssel und fordert die unveränderliche Erstellung der Zahlung API Wealth Readeran.

Standardmodell für Händler (Eigener Begünstigter)

Der Händler gibt sein Inkassokonto, den Betrag in Cent (amount_minor), die Zahlungsreferenz und den Webursprung an, an dem das Widget geladen wird:

: "${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"
  }'

Hinweis: allowed_institution_codes ist optional. Wenn es weggelassen wird, kann der Benutzer aus allen Entitäten im Katalog wählen.

Modell mit verwaltetem Profil (Spendendemonstration)

Wenn du das verwaltete Profil integrierst 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"
  }'

Antwort der API

Das API reagiert, indem es die unveränderliche Absicht bestätigt und die Daten zur Initialisierung des Widgets liefert:

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

Ihr Backend darf dem Browser des Nutzers ausschließlich die payment.id und payment.widget.tokenliefern.

3. Montiere das Widget am Frontend

Es gibt zwei Möglichkeiten, das Widget in Ihrer Weboberfläche zu mounten: mit dem offiziellen deklarativen Skript oder mit dem programmatischen JavaScript- API .

Option A: Über das deklarative Skript (load-payments.js)

Binden Sie den Container und das Ladeskript in Ihre Checkout-Seite ein.

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

Option B: Über JavaScript API (WealthReaderPayments.mount)

Wenn du Frameworks wie React, Vue, Angular oder einen SPA Flow verwendest:

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'
});

Das Widget erhält die Konfiguration direkt von den Wealth Reader Servern mit dem nur einmal verwendbaren Token . Wenn die Bank verlangt, dass das Debitkonto vor der Weiterleitung identifiziert wird, fordert das Widget die IBAN direkt vom Zahler an, ohne dass der Händler sie bearbeiten muss.

Widget-Hauptevents

Nächster Schritt

Rezension Absichten und Idempotenz.