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

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.

Príomhimeachtaí na giuirléide

An chéad chéim eile

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