Betalingsintegration & Widget

API-nøglen (X-API-Key) bør aldrig optræde i HTML, klient-JavaScript, browserlogs eller URL-parametre.

1. Register over bankenheder

For at finde ud af, hvilke banker der er tilgængelige, og få deres logoer, navne og krav, kan du tjekke enhedens endepunkt direkte fra dens backend. Hver enhed leveres med to logoer: logo, det som Wealth Reader anbefalet at vise (sit eget vektorlogo, når det findes, ellers udbyderens logo, ifølge logo_source), og logo_fallback, udbyderens, så dens interface kan bruge det, hvis det første ikke indlæses:

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

Dette endpoint er offentligt: send ikke X-API-Key. Det ændrer ikke svaret, det bruger et kald fra din kvote, og hvis betalinger blev deaktiveret på din konto, ville det konvertere en fungerende forespørgsel til en 503.

Den understøtter også valgfrie forespørgselsparametre:

• country: ISO tobogstavskode (f.eks. ES, FR, DE, IT, PT...). Med ALL eller tom filtreres den ikke efter land.
• search (alias q): tekstsøgning efter navn eller kode (f.eks. santander, bbva).
• code- Henter en specifik enhed ved dens nøjagtige kode.
• payment_method: Filtrer efter understøttet metode (f.eks. sepa_credit_transfer).
• limit og offset: paginering af resultater.

Eksempel på et kort svar:

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

Anbefalet mønster til at vise logo med automatisk bagside:

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

I /payments/entities/ er begge felter altid til stede og null , når der ikke er noget logo. POST /payments/?action=profile-institutions - og widget-institutionerne har samme logo og logo_fallback som valgfrie felter: de mangler, når der ikke er noget brugbart logo. Logoer peger kun på cdn.wealthreader.com eller assets.exthand.com; hvis din side har CSP, tilføj begge værter til img-src.

Administrerede profiler (såsom donationsdemoen): Hvis du bruger en forudkonfigureret profil som cruz_roja_demo, så forespørg de institutioner og betingelser, serveren har sat, ved at kalde POST /payments/?action=profile-institutions med {"profile": "cruz_roja_demo"}body.

2. Skab en betalingsintention i backend

Når kunden beslutter at betale ved kassen, genererer deres server en unik idempotensnøgle og anmoder om den uforanderlige oprettelse af betalingen på API af Wealth Reader.

Standardmodel for handlende (egen begunstiget)

Forhandleren angiver sin inkassokonto, beløbet i cent (amount_minor), betalingsreferencen og weboprindelsen, hvor widgetten vil indlæses:

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

Bemærk: allowed_institution_codes er valgfrit. Hvis det udelades, vil brugeren kunne vælge blandt alle enheder i kataloget.

Model med administreret profil (donationsdemonstration)

Hvis du integrerer den administrerede profil 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"
  }'

Svar fra API

API svarer ved at bekræfte den uforanderlige hensigt og levere dataene til at initialisere widgetten:

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

Din backend bør kun levere til brugerens browser payment.id og payment.widget.token.

3. Monter widgetten på frontend

Der er to måder at montere widgetten i din webgrænseflade: ved at bruge det officielle deklarative script eller ved at bruge det programmatiske JavaScript API .

Mulighed A: Via deklarativt script (load-payments.js)

Indlejr beholderen og opladeren på din kasseside:

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

Mulighed B: Via JavaScript API (WealthReaderPayments.mount)

Hvis du bruger frameworks som React, Vue, Angular eller et SPA-flow:

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

Widgetten får konfigurationen direkte fra de Wealth Reader servere med engangs- token . Hvis banken kræver, at debetkontoen identificeres, før den omdirigeres, anmoder widgetten om IBAN direkte fra betaleren uden at forhandleren behøver at behandle den.

Widget Hovedbegivenheder

Næste skridt

Anmeldelse Intentioner og idempotens.