Πληρωμές με Wealth Reader

Αρχιτεκτονική σε δύο βήματα

Η ενοποίηση πληρωμών ακολουθεί έναν αυστηρό διαχωρισμό των ευθυνών σε δύο βήματα:

sequenceDiagram
autonumber
actor Usuario as Χρήστης
participant Front as Frontend (Εμπόριο)
participant Back as Backend (Εμπόριο)
participant API as API Wealth Reader
participant Widget as Πληρωμές widget
participant Banco as Τράπεζα (SCA)
Note over Back,API: Προηγούμενο βήμα (μόνο διαχειριζόμενα προφίλ)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Κατάλογος προφίλ (institution_code)
Note over Back,API: Βήμα 1: Δημιουργία της αμετάβλητης πρόθεσης (Server-to-Server)
Back->>API: POST /payments/?action=create (με X-API-Key και Idempotency-Key)
API-->>Back: 201 με payment.id + payment.widget.token εφήμερο
Note over Front,Widget: Βήμα 2: Μεταφόρτωση και εξουσιοδότηση στο γραφικό στοιχείο (πρόγραμμα περιήγησης)
Back->>Front: Παράδοση payment.id και payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) ή load-payments.js
Widget->>Usuario: Έχει αμετάβλητη οντότητα, ποσότητα και έννοια
Usuario->>Widget: Εξουσιοδότηση πληρωμής
Widget->>Banco: Ανακατεύθυνση / Εφαρμογή σε εφαρμογή (SCA)
Banco->>API: Επιστροφή του SCA στο callback του Wealth Reader
API-->>Widget: Τεχνική επιβεβαίωση της έγκρισης
Note over Back,API: Οικονομική Συμφωνία και Επιβεβαίωση
loop Σε κατάσταση τερματικού
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Βήμα 1 (Ασφαλές Backend): Ο διακομιστής σας δημιουργεί μια πρόθεση πληρωμής (POST /payments/?action=create) με το X-API-Keyσας, ένα Idempotency-Key και Content-Type: application/json. Σε αυτήν την κλήση, το ποσό (amount_minor, σε σεντ), το νόμισμα (currency, σήμερα μόνο EUR), ο δικαιούχος (beneficiary.name και beneficiary.iban), η έννοια της δήλωσης (reference), η εσωτερική της αναφορά (customer_reference) και η επιτρεπόμενη προέλευση ιστού (allowed_origin) καθορίζονται αμετάβλητα. Αυτά τα έξι πεδία είναι υποχρεωτικά και το σώμα είναι μια αυστηρή λευκή λίστα: κάθε μη αναγνωρισμένο πεδίο επιστρέφει 422 invalid_request.
2. Απάντηση: 201 με {"success": true, "payment": {…}} — ή 200 εάν πρόκειται για επανάληψη με το ίδιο κλειδί idempotency. Το αναγνωριστικό πρόθεσης έρχεται σε payment.id και η εφήμερη token του γραφικού στοιχείου σε payment.widget.token.
3. Βήμα 2 (Frontend της συναλλαγής): Το πρόγραμμα περιήγησης προσαρτά το γραφικό στοιχείο χρησιμοποιώντας το επίσημο σενάριο load-payments.js ή τη λειτουργία WealthReaderPayments.mount(), παρέχοντας μόνο το payment.id και το payment.widget.token. Ο χρήστης επιλέγει την τράπεζά του (αν δεν ήταν προεπιλεγμένη στην πρόθεση) και ολοκληρώνει τον ισχυρό έλεγχο ταυτότητας (SCA) στην τραπεζική διεπαφή.
4. Οικονομική επιβεβαίωση: Το backend σας ελέγχει την κατάσταση χρησιμοποιώντας POST /payments/?action=status, του οποίου το σώμα είναι ακριβώς {"payment_intent_id": "<id>"}. Χωρίς webhook: Ελέγχει περιοδικά την κατάσταση μέχρι να φτάσει σε μια τερματική κατάσταση.

Δύο μοντέλα πληρωμής

Wealth Reader υποστηρίζει δύο μοντέλα ανάλογα με τις ανάγκες της επιχείρησης:

1. Τυπική ενσωμάτωση για εμπόρους (ίδιος δικαιούχος):
   • Ο έμπορος ορίζει ελεύθερα το όνομα και το IBAN του δικαιούχου, το ποσό, το νόμισμα (EUR), την έννοια και την αναφορά της παραγγελίας του.
   • Μπορείτε να φιλτράρετε ποιες τράπεζες θα είναι διαθέσιμες στο χρήστη χρησιμοποιώντας allowed_institution_codes ή να επιτρέψετε ολόκληρο τον κατάλογο.
2. Διαχειριζόμενα προφίλ (όπως cruz_roja_demo):
   • Σχεδιασμένο για δωρεές και δημόσιες επιδείξεις.
   • Ο διακομιστής ορίζει τους επίσημους λογαριασμούς προορισμού για να διασφαλίσει ότι τα χρήματα μπορούν να κατευθυνθούν μόνο στη φιλανθρωπική οργάνωση (για παράδειγμα, στον Ισπανικό Ερυθρό Σταυρό με ποσά μεταξύ 0,01 EUR και 1,00 EUR).

Ενιαίος κατάλογος τραπεζικών οντοτήτων

Wealth Reader παρέχει έναν ενοποιημένο κατάλογο ευρωπαϊκών οντοτήτων που καταρτίζονται για την έναρξη πληρωμών μέσω PSD2 μέσω:

• GET https://api.wealthreader.com/payments/entities/?country=ES

Σας επιτρέπει να λάβετε τη λίστα των τραπεζών με τα τυποποιημένα ονόματα, τα λογότυπά τους, τις υποστηριζόμενες μεθόδους μεταφοράς και τις τεχνικές απαιτήσεις (όπως η ανάγκη να ζητήσετε την IBAN του οφειλέτη από τον πληρωτή). Υποστηρίζει τα φίλτρα country, search (ψευδώνυμο q), code, payment_method, limit και offset.

Αυτό το τελικό σημείο είναι δημόσιο: δεν απαιτεί X-API-Key. Η αποστολή του δεν συνεισφέρει τίποτα και καταναλώνει μια κλήση από το όριο του κωδικού πρόσβασής σας.

Χρησιμοποιείτε πάντα αυτούς τους κωδικούς καθώς έρχονται code. Η δημιουργία της πρόθεσης επικυρώνει τη μορφοποίηση allowed_institution_codes, αλλά δεν ελέγχει ότι υπάρχουν στον κατάλογο: ο ανορθόγραφος κώδικας δεν αποτυγχάνει κατά τη δημιουργία και εμφανίζεται αργότερα ως κενός επιλογέας τράπεζας.

Διαχωρισμός ευθυνών

• Το κλειδί πρόσβασης πληρωμής (X-API-Key) χρησιμοποιείται μόνο από διακομιστή σε διακομιστή. Δεν πρέπει ποτέ να περιλαμβάνεται σε frontend ή δημόσια αποθετήρια.
• Το πρόγραμμα περιήγησης λαμβάνει μόνο το αναγνωριστικό της πρόθεσης και μια βραχύβια εφήμερη token που συνδέεται με την προέλευση HTTPS.
• Το widget δεν μπορεί να αλλάξει το ποσό, το νόμισμα, τον δικαιούχο, την έννοια ή τα εξουσιοδοτημένα ιδρύματα.
• Το κλείσιμο του modal ή του widget δεν υποκαθιστά την αναζήτηση της οικονομικής κατάστασης στο backend.
• Οι πληρωμές δεν μοιράζονται κλειδιά πρόσβασης, διακριτικά ή επανακλήσεις με το προϊόν συγκέντρωσης τραπεζών της Wealth Reader.

Διαπιστευτήρια και όριο κλήσεων

Το κλειδί πρόσβασης πληρωμών πρέπει να έχει ενεργοποιημένο το προϊόν PAYMENTS . Εάν όχι, το API αποκρίνεται 403 payments_not_allowed. Ένα κλειδί πρόσβασης που λείπει ή δεν έχει μορφοποιηθεί σωστά επιστρέφει 401 invalid_api_key.

Επόμενο βήμα

Συνέχισε με Ενσωμάτωση και widget.