Comhtháthú agus giuirléid íocaíochtaí

Ní ceadmhach don eochair API (X-API-Key) a bheith le feiceáil riamh in HTML, i JavaScript an chliaint, i logaí an bhrabhsálaí ná i bparaiméadair URL.

1. Eolaire na n-institiúidí baincéireachta

Chun na bainc atá ar fáil, a lógónna, a n-ainmneacha agus a riachtanais a fháil, is féidir leat pointe deiridh na n-institiúidí a cheistiú go díreach ó do backend. Tá dhá lógó ag gach institiúid: logo, an lógó a mholann Wealth Reader a thaispeáint (a lógó veicteoireach féin má tá sé ar fáil, nó lógó an tsoláthraí mura bhfuil, de réir logo_source), agus logo_fallback, lógó an tsoláthraí, le húsáid mura lódálann an chéad cheann:

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

Tá an pointe deiridh seo poiblí: ná seol X-API-Key. Ní athraíonn sé sin an freagra, ídíonn sé glao amháin de do chuóta agus, má tá íocaíochtaí díchumasaithe ar do chuntas, athróidh sé iarratas a d’oibreodh ina fhreagra 503.

Glacann sé leis na paraiméadair roghnacha seo freisin:

• country: cód ISO dhá litir (m.sh. ES, FR, DE, IT, PT...). Le ALL nó luach folamh, ní dhéantar scagadh de réir tíre.
• search (ailias q): cuardach téacs de réir ainm nó cóid (m.sh. santander, bbva).
• code: faigh institiúid ar leith lena cód cruinn.
• payment_method: scag de réir modh tacaithe (m.sh. sepa_credit_transfer).
• limit agus offset: leathanú na dtorthaí.

Sampla giorraithe den fhreagra:

{
  "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 is cumas breathnaithe de réir institiúide é, ní riail de réir tíre. Nuair atá sé false, ní iarrann ná ní sheolann an ghiuirléid IBAN na cuntais foinse agus roghnaíonn an t-íocóir an cuntas ar scáileán slán an bhainc. Nuair atá sé true, éilíonn an ghiuirléid an IBAN roimh an atreorú. Deimhníonn na roghanna táirgeachta a breathnaíodh an 10 Meán Fómhair 2026 an luach false do Santander 976 i gcás SEPA gnáth agus SEPA meandrach; níor fíoraíodh fós, le SCA tar éis an athraithe, an scáileán bainc ina roghnaítear an cuntas.

Déanann payment_methods cur síos ar na cumais a fhoilsíonn an institiúid. Faoi láthair, ní thionscnaíonn an taispeántas demo-all-pay ach SEPA gnáth; ní thairgeann sé roghnóir tosaíochta agus ní thionscnaíonn sé íocaíochtaí meandracha.

Patrún molta chun an lógó a thaispeáint le malairt uathoibríoch:

<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/, bíonn an dá réimse ann i gcónaí agus is é null a luach nuair nach bhfuil lógó ann. In institiúidí ó POST /payments/?action=profile-institutions agus ón ngiuirléid, is réimsí roghnacha iad na réimsí céanna logo agus logo_fallback: ní bhíonn siad ann nuair nach bhfuil lógó inúsáidte ar fáil. Ní dhíríonn na lógónna ach ar cdn.wealthreader.com nó assets.exthand.com; má tá CSP ar do leathanach, cuir an dá óstach le img-src.

Próifílí bainistithe (mar an taispeántas síntiús): Má úsáideann tú próifíl réamhchumraithe ar nós cruz_roja_demo, faigh na hinstitiúidí agus na coinníollacha a shocraíonn an freastalaí trí ghlaoch ar POST /payments/?action=profile-institutions leis an gcorp {"profile": "cruz_roja_demo"}.

2. Rún íocaíochta a chruthú ar an backend

Nuair a chinneann an custaiméir íoc ag an tseiceáil amach, gineann do fhreastalaí eochair uathúil idempotency agus iarrann sé ar API Wealth Reader an íocaíocht do-athraithe a chruthú.

Samhail chaighdeánach do cheannaithe (Tairbhí dá gcuid féin)

Sonraíonn an ceannaí a chuntas glactha, an méid i gceinteanna (amount_minor), tagairt na híocaíochta agus an bunús gréasáin ina luchtófar an ghiuirléid:

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

Nóta: tá allowed_institution_codes roghnach. Má fhágtar ar lár é, is féidir leis an úsáideoir aon institiúid sa chatalóg a roghnú.

Samhail le próifíl bhainistithe (Taispeántas síntiús)

Má chomhtháthaíonn tú an phróifíl bhainistithe 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"
  }'

Freagra an API

Deimhníonn freagra an API an rún do-athraithe agus soláthraíonn sé na sonraí chun an ghiuirléid a thúsú:

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

Ní ceadmhach do do backend ach payment.id agus payment.widget.token a thabhairt do bhrabhsálaí an úsáideora.

3. An ghiuirléid a luchtú ar an frontend

Tá dhá bhealach ann chun an ghiuirléid a luchtú i do chomhéadan gréasáin: an script dhearbhaitheach oifigiúil nó API ríomhchláraithe JavaScript.

Rogha A: Script dhearbhaitheach (load-payments.js)

Leabaigh an coimeádán agus an script luchtaithe i do leathanach seiceála amach:

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

Rogha B: API JavaScript (WealthReaderPayments.mount)

Má úsáideann tú creataí ar nós React, Vue, Angular nó sreabhadh SPA:

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

Faigheann an ghiuirléid an chumraíocht go díreach ó fhreastalaithe Wealth Reader leis an token nach féidir a úsáid ach uair amháin. Má éilíonn an banc an cuntas dochair a aithint roimh atreorú, iarrann an ghiuirléid IBAN an fhéichiúnaí go díreach ar an íocóir; ní gá don cheannaí é a phróiseáil. Má tá an cumas roghnach, fágann an ghiuirléid an fhaisnéis sin ar lár agus míníonn sí go roghnófar an cuntas ar scáileán slán an bhainc.

Príomhimeachtaí na giuirléide

An chéad chéim eile

Léigh Rúin íocaíochta agus idempotency.