Maksujen integraatio ja widget

API-avain (X-API-Key) ei koskaan saa näkyä HTML:ssä, asiakasohjelman JavaScriptissä, selainlokeissa tai URL-parametreissa.

1. Pankkiyksiköiden hakemisto

Jotta voit selvittää, mitkä pankit ovat saatavilla ja saada niiden logot, nimet ja vaatimukset, tarkistamalla entiteettipäätepisteen suoraan sen taustajärjestelmästä. Jokaisella entiteettillä on kaksi logoa: logo, se, jota Wealth Reader suositeltu näyttämään (oma vektorilogo, kun se on olemassa, palveluntarjoajan logo muuten logo_sourcemukaan), ja logo_fallback, palveluntarjoajan, jotta sen käyttöliittymä voi käyttää sitä, jos ensimmäinen ei lataudu:

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

Tämä päätepiste on julkinen: älä lähetä X-API-Key. Tämä ei muuta vastausta, se kuluttaa puhelun kiintiöstäsi, ja jos maksut poistetaan tililtäsi, se muuttaisi toimivan kyselyn 503:ksi.

Se tukee myös valinnaisia kyselyparametreja:

• country: ISO:n kaksikirjaiminen koodi (esim. ES, FR, DE, IT, PT...). Kun koodi on ALL tai tyhjä, sitä ei suodata maittain.
• search (alias q): tekstihaku nimen tai koodin perusteella (esim. santander, bbva).
• code- Hae tietyn olennon sen tarkalla koodilla.
• payment_method: Suodatukset tuetun menetelmän mukaan (esim. sepa_credit_transfer).
• limit ja offset: tulosten sivutus.

Esimerkki lyhyestä vastauksesta:

{
  "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": false
    },
    {
      "code": "ebury-es",
      "name": "Ebury",
      "country": "ES",
      "logo": "https://assets.exthand.com/bsdk/banks/logos/ZZ/ebury.png",
      "logo_fallback": "https://assets.exthand.com/bsdk/banks/logos/ZZ/ebury.png",
      "logo_source": "exthand",
      "payment_methods": ["sepa_credit_transfer"],
      "requires_debtor_iban": true
    }
  ]
}

requires_debtor_iban on toimijan havaitsema kapasiteetti, ei maan sääntö. Kun falseon voimassa, widget ei pyydä tai lähetä lähdettä IBAN ja maksaja valitsee tilin pankin suojatussa näytössä. Kun se on voimassa true, widget vaatii IBAN ennen uudelleenohjausta. 10. syyskuuta 2026 havaitut tuotantovaihtoehdot vahvistavat Santander 976:n false arvon normaalissa ja välittömässä SEPA:ssa; pankkinäyttöä, jossa tili valitaan, ei ole vielä vahvistettu muutoksen jälkeisellä SCA .

payment_methods kuvaa yksikön julkaisemia ominaisuuksia. Demo käynnistää tällä hetkellä vain tavalliset SEPA- demo-all-pay ; se ei tarjoa prioriteettivalitsijaa eikä käynnistä välittömiä maksuja.

Suositeltu tapa näyttää logo ja siirtyä varalogoon automaattisesti:

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

/payments/entities/ molemmat kentät ovat aina läsnä ja null, kun logoa ei ole. POST /payments/?action=profile-institutions- ja widget-instituutioilla on samat logo ja logo_fallback kuin valinnaisina kenttinä: ne puuttuvat, kun käytettävissä ei ole logoa. Logot osoittavat vain cdn.wealthreader.com tai assets.exthand.com; jos sivullasi on CSP, lisää molemmat isännät img-src.

Hallinnoidut profiilit (kuten lahjoitusdemo): Jos käytät ennalta määritettyä profiilia, kuten cruz_roja_demo, kysy palvelimen asettamia laitoksia ja ehtoja kutsumalla POST /payments/?action=profile-institutions {"profile": "cruz_roja_demo"}rungolla.

2. Luo maksuaikomus taustajärjestelmään

Kun asiakas päättää maksaa kassalla, kauppiaan palvelin luo yksilöllisen idempotenssiavaimen ja pyytää Wealth Readerin API:a luomaan muuttumattoman maksuaikomuksen.

Vakiomalli kauppiaille (oma edunsaaja)

Kauppias määrittelee perintätilinsä, summan sentteinä (amount_minor), maksuviitteen ja verkkolähteen, johon widget ladataan:

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

Huomautus: allowed_institution_codes on valinnainen. Jos se jätetään pois, käyttäjä voi valita kaikista luettelon entiteetteistä.

Malli hallinnoitulla profiililla (lahjoitusdemonstraatio)

Jos integroit hallitun profiilin 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"
  }'

Vastaus API

API vastaa vahvistamalla muuttumattoman aikomuksen ja toimittamalla tiedot widgetin alustamista varten:

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

Taustajärjestelmäsi saa toimittaa käyttäjän selaimelle vain payment.id ja payment.widget.token.

3. Kiinnitä widget etuosaan

Widgetin liittämiseen verkkokäyttöliittymään on kaksi tapaa: käyttää virallista deklaratiivista skriptiä tai ohjelmallista JavaScript- API .

Vaihtoehto A: Deklaratiivisen skriptin (load-payments.js) kautta

Upota widgetin säiliö ja latausskripti kassasivullesi:

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

Vaihtoehto B: JavaScriptin kautta API (WealthReaderPayments.mount)

Jos käytät kehyksiä kuten React, Vue, Angular tai 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'
});

Widget saa konfiguraation suoraan Wealth Reader palvelimilta, ja token voi käyttää vain kerran. Jos pankki vaatii debittilin tunnistamisen ennen uudelleenohjausta, widget pyytää debit IBAN suoraan maksajalta ilman, että kauppiaan tarvitsee käsitellä sitä. Jos kapasiteetti on valinnainen, widget jättää tämän tiedon pois ja varoittaa, että tili valitaan pankin suojatulla näytöllä.

Widgetin päätapahtumat

Seuraava askel

Arvostelu Aikomukset ja idempotentti.