Ενσωμάτωση πληρωμών & Widget

Το κλειδί API (X-API-Key) δεν πρέπει ποτέ να εμφανίζεται σε παραμέτρους HTML, JavaScript πελάτη, αρχεία καταγραφής προγράμματος περιήγησης ή URL.

1. Κατάλογος τραπεζικών οντοτήτων

Για να μάθετε ποιες τράπεζες είναι διαθέσιμες και να λάβετε τα λογότυπα, τα ονόματα και τις απαιτήσεις τους, μπορείτε να ελέγξετε το τελικό σημείο της οντότητας απευθείας από το backend της. Κάθε οντότητα συνοδεύεται από δύο λογότυπα: logo, αυτό που Wealth Reader συνιστάται να εμφανίζεται (το δικό της διανυσματικό λογότυπο όταν υπάρχει, το λογότυπο του παρόχου διαφορετικά, σύμφωνα με logo_source) και logo_fallback, του παρόχου, έτσι ώστε η διεπαφή του να μπορεί να το χρησιμοποιήσει εάν το πρώτο δεν φορτώσει:

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

Αυτό το τελικό σημείο είναι δημόσιο: μην στέλνετε X-API-Key. Με αυτόν τον τρόπο δεν αλλάζει η απάντηση, καταναλώνει μια κλήση από το όριο σας και εάν οι πληρωμές ήταν απενεργοποιημένες στον λογαριασμό σας, θα μετέτρεπε ένα λειτουργικό ερώτημα σε 503.

Υποστηρίζει επίσης προαιρετικές παραμέτρους ερωτήματος:

• country: Κωδικός ISO δύο γραμμάτων (π.χ. ES, FR, DE, IT, PT...). Με ALL ή κενό δεν φιλτράρεται ανά χώρα.
• search (γνωστός και ως q): αναζήτηση κειμένου με βάση το όνομα ή τον κωδικό (π.χ. santander, bbva).
• code- Ανακτά μια συγκεκριμένη οντότητα με τον ακριβή κωδικό της.
• payment_method: Φιλτράρει με υποστηριζόμενη μέθοδο (π.χ. sepa_credit_transfer).
• limit και offset: σελιδοποίηση των αποτελεσμάτων.

Δείγμα σύντομης απάντησης:

{
  "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 είναι μια χωρητικότητα που παρατηρείται ανά οντότητα και όχι ένας κανόνας ανά χώρα. Όταν falseείναι έγκυρη, το widget δεν ζητά ούτε στέλνει την πηγή IBAN και ο πληρωτής επιλέγει τον λογαριασμό στην ασφαλή οθόνη της τράπεζας. Όταν είναι έγκυρο true, το widget απαιτεί το IBAN πριν από την ανακατεύθυνση. Οι επιλογές παραγωγής που παρατηρήθηκαν στις 10 Σεπτεμβρίου 2026 επιβεβαιώνουν την τιμή false για το Santander 976 σε κανονικό και άμεσο SEPA. Η οθόνη τράπεζας όπου έχει επιλεγεί ο λογαριασμός δεν έχει ακόμη επαληθευτεί από SCA μετά την αλλαγή.

payment_methods περιγράφει τις δυνατότητες που δημοσιεύονται από την οντότητα. Η επίδειξη προς το παρόν ξεκινά μόνο κανονικές demo-all-pay SEPA. Δεν προσφέρει επιλογέα προτεραιότητας ούτε ξεκινά άμεσες πληρωμές.

Προτεινόμενο μοτίβο για εμφάνιση λογότυπου με αυτόματη υποστήριξη:

<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/ και τα δύο πεδία είναι πάντα παρόντα και null όταν δεν υπάρχει λογότυπο. Τα ιδρύματα POST /payments/?action=profile-institutions και widget φέρουν την ίδια logo και logo_fallback με τα προαιρετικά πεδία: λείπουν όταν δεν υπάρχει χρησιμοποιήσιμο λογότυπο. Τα λογότυπα δείχνουν μόνο cdn.wealthreader.com ή assets.exthand.com. Εάν η σελίδα σας έχει CSP, προσθέστε και τους δύο κεντρικούς υπολογιστές στο img-src.

Διαχειριζόμενα προφίλ (όπως η επίδειξη δωρεάς): Εάν χρησιμοποιείτε ένα προδιαμορφωμένο προφίλ, όπως το cruz_roja_demo, ρωτήστε τους θεσμούς και τις συνθήκες που έχει ορίσει ο διακομιστής καλώντας POST /payments/?action=profile-institutions με τον {"profile": "cruz_roja_demo"}φορέα.

2. Δημιουργήστε μια πρόθεση πληρωμής στο backend

Όταν ο πελάτης αποφασίσει να πληρώσει στο ταμείο του, ο διακομιστής του δημιουργεί ένα μοναδικό κλειδί idempotency και ζητά την αμετάβλητη δημιουργία της πληρωμής στο API του Wealth Reader.

Τυποποιημένο υπόδειγμα για εμπόρους (ίδιος δικαιούχος)

Ο έμπορος καθορίζει τον λογαριασμό είσπραξης, το ποσό σε σεντ (amount_minor), την αναφορά πληρωμής και την προέλευση ιστού όπου θα φορτωθεί το γραφικό στοιχείο:

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

Σημείωση: allowed_institution_codes είναι προαιρετική. Εάν παραλειφθεί, ο χρήστης θα μπορεί να επιλέξει από όλες τις οντότητες στον κατάλογο.

Μοντέλο με Διαχειριζόμενο Προφίλ (Επίδειξη Δωρεάς)

Εάν ενσωματώσετε το διαχειριζόμενο προφίλ 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"
  }'

Απάντηση από το API

Το API ανταποκρίνεται επιβεβαιώνοντας την αμετάβλητη πρόθεση και παραδίδοντας τα δεδομένα για την προετοιμασία του γραφικού στοιχείου:

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

Το backend σας θα πρέπει να παραδίδει στο πρόγραμμα περιήγησης του χρήστη μόνο το payment.id και το payment.widget.token.

3. Τοποθετήστε το γραφικό στοιχείο στο frontend

Υπάρχουν δύο τρόποι για να προσαρτήσετε το γραφικό στοιχείο στη διεπαφή ιστού σας: χρησιμοποιώντας το επίσημο δηλωτικό σενάριο ή χρησιμοποιώντας την προγραμματική API JavaScript.

Επιλογή Α: Μέσω δηλωτικής γραφής (load-payments.js)

Ενσωματώστε το δοχείο και τον φορτιστή στη σελίδα ολοκλήρωσης αγοράς:

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

Επιλογή Β: Μέσω JavaScript API (WealthReaderPayments.mount)

Εάν χρησιμοποιείτε πλαίσια όπως το React, το Vue, το Angular ή μια ροή 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'
});

Το widget λαμβάνει τη διαμόρφωση απευθείας από τους διακομιστές Wealth Reader με το token να μπορεί να χρησιμοποιηθεί μόνο μία φορά. Εάν η τράπεζα απαιτεί την ταυτοποίηση του χρεωστικού λογαριασμού πριν από την ανακατεύθυνση, το widget ζητά τη χρεωστική IBAN απευθείας από τον πληρωτή χωρίς να χρειάζεται να την επεξεργαστεί ο έμπορος. Εάν η χωρητικότητα είναι προαιρετική, το widget παραλείπει αυτές τις πληροφορίες και προειδοποιεί ότι ο λογαριασμός θα επιλεγεί στην ασφαλή οθόνη της τράπεζας.

Κύρια γεγονότα Widget

Επόμενο βήμα

Ανασκόπηση Προθέσεις και idempotency.