Betalingsintegrasjon og widget

API-nøkkelen (X-API-Key) skal aldri vises i HTML, klient-JavaScript, nettleserlogger eller URL-parametere.

1. Katalog over bankenheter

For å finne ut hvilke banker som er tilgjengelige og få deres logoer, navn og krav, kan du sjekke enhetens endepunkt direkte fra backend. Hver enhet har to logoer: logo, den som Wealth Reader anbefalt å vise (sin egen vektorlogo når den finnes, ellers leverandørens logo, ifølge logo_source), og logo_fallback, leverandørens, slik at grensesnittet kan bruke den hvis den første ikke lastes inn:

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

Dette endepunktet er offentlig: ikke send X-API-Key. Å gjøre dette endrer ikke svaret, det bruker et kall fra kvoten din, og hvis betalinger var deaktivert på kontoen din, ville det konvertere en fungerende spørring til en 503.

Den støtter også valgfrie spørringsparametere:

• country: ISO to-bokstavskode (f.eks. ES, FR, DE, IT, PT...). Med ALL eller tom filtreres den ikke etter land.
• search (alias q): tekstsøk etter navn eller kode (f.eks. santander, bbva).
• code- Henter en spesifikk enhet ved dens eksakte kode.
• payment_method: Filtrer etter støttet metode (f.eks. sepa_credit_transfer).
• limit og offset: paginering av resultater.

Eksempel på 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
    }
  ]
}

Anbefalt mønster for å vise logo med automatisk reservelogo:

<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 feltene alltid til stede og null når det ikke finnes noen logo. Institusjonene POST /payments/?action=profile-institutions og widget har samme logo og logo_fallback som valgfrie felt: de mangler når det ikke finnes noen brukbar logo. Logoer peker kun på cdn.wealthreader.com eller assets.exthand.com; hvis siden din har CSP, legg til begge vertene i img-src.

Administrerte profiler (som donasjonsdemoen): Hvis du bruker en forhåndskonfigurert profil som cruz_roja_demo, spør institusjonene og betingelsene satt av serveren ved å kalle POST /payments/?action=profile-institutions med {"profile": "cruz_roja_demo"}body.

2. Lag en betalingsintensjon på backend

Når kunden bestemmer seg for å betale i kassen, genererer serveren en unik idempotensnøkkel og ber om uforanderlig opprettelse av betalingen på API av Wealth Reader.

Standardmodell for handelsmenn (egen begunstiget)

Forhandleren spesifiserer sin innkrevingskonto, beløpet i cent (amount_minor), betalingsreferansen og nettopprinnelsen der widgeten skal lastes:

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

Merk: allowed_institution_codes er valgfritt. Hvis det utelates, vil brukeren kunne velge blant alle enheter i katalogen.

Modell med administrert profil (Donasjonsdemonstrasjon)

Hvis du integrerer den administrerte profilen 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 å bekrefte den uforanderlige intensjonen og levere dataene for å initialisere widgeten:

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

Backenden din skal levere til brukerens nettleser kun payment.id og payment.widget.token.

3. Monter widgeten på frontend

Det finnes to måter å montere widgeten på i nettgrensesnittet ditt: ved å bruke det offisielle deklarative skriptet eller ved å bruke det programmatiske JavaScript- API .

Alternativ A: Via deklarativt skript (load-payments.js)

Legg inn containeren og lasteskriptet på kassesiden din:

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

Alternativ B: Via JavaScript API (WealthReaderPayments.mount)

Hvis du bruker rammeverk som React, Vue, Angular eller en SPA-flyt:

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

Widgeten henter konfigurasjonen direkte fra Wealth Reader serverne, hvor token kun kan brukes én gang. Hvis banken krever identifikasjon av debetkontoen før omdirigering, ber widgeten om debetkontoen IBAN direkte fra betaleren uten at forhandleren trenger å behandle den.

Widget Hovedarrangementer

Neste steg

Anmeldelse Intensjoner og idempotens.