Integratie van betalingen & widget

De API -sleutel (X-API-Key) mag nooit voorkomen in HTML, client JavaScript, browserlogs of URL-parameters.

1. Directory van bankentiteiten

Om te achterhalen welke banken beschikbaar zijn en hun logo's, namen en vereisten te krijgen, kun je het entiteitseindpunt direct vanuit de backend controleren. Elke entiteit wordt geleverd met twee logo's: logo, het logo dat Wealth Reader aanbevolen om weer te geven (het eigen vectorlogo wanneer het bestaat, anders het logo van de aanbieder, volgens logo_source), en logo_fallback, dat van de aanbieder, zodat de interface het kan gebruiken als het eerste niet laadt:

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

Dit eindpunt is openbaar: stuur geen X-API-Key mee. Dit verandert het antwoord niet, het verbruikt een oproep van je quotum, en als betalingen in je account worden uitgeschakeld, zou het een werkende query omzetten in een 503.

Het ondersteunt ook optionele queryparameters:

• country: ISO tweeletterige code (bijv. ES, FR, DE, IT, PT...). Met ALL of leeg wordt het niet gefilterd op land.
• search (alias q): tekstuele zoekopdracht op naam of code (bijv. santander, bbva).
• code- Haalt een specifieke entiteit op via de exacte code.
• payment_method: Filters op ondersteunde methode (bijv. sepa_credit_transfer).
• limit en offset: paginering van resultaten.

Voorbeeld van een kort antwoord:

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

Aanbevolen patroon om het logo te tonen met automatische terugval op een alternatief logo:

<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/ zijn beide velden altijd aanwezig en zijn ze null wanneer er geen logo is. De POST /payments/?action=profile-institutions - en banken die de widget retourneert dragen dezelfde logo en logo_fallback als optionele velden: ze ontbreken wanneer er geen bruikbaar logo is. Logo's verwijzen alleen naar cdn.wealthreader.com of assets.exthand.com; als je pagina CSP heeft, voeg dan beide hosts toe aan img-src.

Beheerde profielen (zoals de donatiedemo): Als je een vooraf geconfigureerd profiel zoals cruz_roja_demogebruikt, vraag dan de banken en voorwaarden op die door de server zijn ingesteld door POST /payments/?action=profile-institutions aan te roepen met het {"profile": "cruz_roja_demo"}body.

2. Een betalingsintentie creëren aan de backend

Wanneer de klant bij het afrekenen besluit te betalen, genereert de server van de handelaar een unieke idempotentiesleutel en vraagt deze de API van Wealth Reader om een onveranderlijke betalingsintentie aan te maken.

Standaardmodel voor handelaren (Eigen begunstigde)

De handelaar specificeert zijn incassorekening, het bedrag in centen (amount_minor), de betalingsreferentie en de weboorsprong waar de widget zal laden:

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

Opmerking: allowed_institution_codes is optioneel. Als het wordt weggelaten, kan de gebruiker kiezen uit alle entiteiten in de catalogus.

Model met beheerd profiel (Donatiedemonstratie)

Als je het beheerde profiel integreert 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"
  }'

Reactie van de API

De API reageert door de onveranderlijke intentie te bevestigen en de data te leveren om de widget te initialiseren:

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

Je backend mag uitsluitend payment.id en payment.widget.token aan de browser van de gebruiker leveren.

3. Monter de widget op de frontend

Er zijn twee manieren om de widget in je webinterface te mounten: met het officiële declaratieve script of met de programmatic JavaScript API .

Optie A: Via declaratief script (load-payments.js)

Embed de container en laadscript op je afrekenpagina:

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

Optie B: Via JavaScript API (WealthReaderPayments.mount)

Als je frameworks gebruikt zoals React, Vue, Angular of een 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'
});

De widget verkrijgt de configuratie rechtstreeks van de Wealth Reader servers waarbij de token slechts één keer bruikbaar is. Als de bank de identificatie van de debetrekening vereist voordat deze wordt doorgestuurd, vraagt de widget de IBAN debetrekening direct bij de betaler op zonder dat de handelaar deze hoeft te verwerken.

Widget Hoofdgebeurtenissen

Volgende stap

Recensie Intenties en idempotentie.