Πληρωμές

Προθέσεις πληρωμής και idempotency

Η πρόθεση πληρωμής ορίζει αμετάβλητα τους οικονομικούς όρους της συναλλαγής πριν ο χρήστης αλληλεπιδράσει με το γραφικό στοιχείο. Αυτό αποτρέπει έναν κακόβουλο πελάτη από το να παραβιάσει το ποσό, τον λογαριασμό προορισμού ή την ιδέα μεταφοράς στο frontend.

Παράμετροι δημιουργίας (`POST /payments/?action=create`)

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

Σε αυτό το μοντέλο, ο έμπορος ορίζει όλα τα δεδομένα συλλογής:

Πεδίο	Τύπος	Απαιτείται	Περιγραφή και κανόνες
`amount_minor`	Ακέραιος	Ναι	Ποσό σε μικρότερες μονάδες (σεντ). Για παράδειγμα, `1500` αντιπροσωπεύει `15,00 EUR`.
`currency`	Συμβολοσειρά	Ναι	Κωδικός νομίσματος 3 γραμμάτων ISO 4217. Επί του παρόντος `EUR`.
`beneficiary`	Αντικείμενο	Ναι	Δεδομένα λογαριασμού προορισμού: `name` (κάτοχος, 1 έως 140 χαρακτήρες κειμένου) και `iban` (έγκυροIBAN χωρίς κενά, με επιλεγμένο ψηφίο ελέγχου). Υποστηρίζει μόνο αυτά τα δύο κλειδιά.
`reference`	Συμβολοσειρά	Ναι	Η έννοια είναι ορατή στο αντίγραφο κίνησης τραπεζικού λογαριασμού (έως 140 χαρακτήρες κειμένου).
`customer_reference`	Συμβολοσειρά	Ναι	Εσωτερικό αναγνωριστικό της παραγγελίας ή του πελάτη σας (1 έως 128 χαρακτήρες κειμένου: γράμματα, αριθμοί, `.`, `_`, `:` `-`, πρέπει να ξεκινούν με γράμμα ή αριθμό).
`allowed_origin`	Συμβολοσειρά	Ναι	Ακριβής HTTPS πηγή που θα ενσωματώσει το widget (π.χ. `https://tienda.example.com`), χωρίς διαδρομή.
`allowed_institution_codes`	Πίνακας	Όχι	Λίστα επιτρεπόμενων κωδικών οντοτήτων (π.χ. `["santander-es", "bbva-es"]`). Εάν παραλειφθεί, επιτρέπεται οποιαδήποτε οντότητα στον κατάλογο.
`locale`	Συμβολοσειρά	Όχι	Η γλώσσα της διεπαφής του γραφικού στοιχείου. Μόνο `es`γίνονται αποδεκτοί σε αυτήν την έκδοση. οποιαδήποτε άλλη τιμή επιστρέφει `422 invalid_locale`.
`expected_mode`	Συμβολοσειρά	Όχι	`mock` ή `live`. Ελέγχει ότι καλείτε το αναμενόμενο περιβάλλον. Δεν αλλάζει περιβάλλοντα. Εάν δεν ταιριάζει, `409 payment_mode_mismatch`.

Το σώμα είναι μια αυστηρή λίστα επιτρεπόμενων: η αποστολή ενός πεδίου που δεν βρίσκεται σε αυτόν τον πίνακα επιστρέφει 422 invalid_request, όπως και η παράλειψη ενός υποχρεωτικού. Η κεφαλίδα Content-Type: application/json είναι υποχρεωτική (415 json_required) και το σώμα περιορίζεται στα 32 KB.

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

Για ρυθμιζόμενες περιπτώσεις ή δημόσιες επιδείξεις όπως cruz_roja_demo, ο διακομιστής επιβάλλει τους οικονομικούς κανόνες και ορίζει τους επίσημους λογαριασμούς-στόχους:

Πεδίο	Τύπος	Απαιτείται	Περιγραφή και κανόνες
`profile`	Συμβολοσειρά	Ναι	Αναγνωριστικό προφίλ (π.χ. `cruz_roja_demo`).
`institution_code`	Συμβολοσειρά	Ναι	Κωδικός οντότητας που έχει επιλεγεί από το χρήστη (από `profile-institutions`).
`amount_minor`	Ακέραιος	Ναι	Ποσό που περιορίζεται από τις πολιτικές προφίλ (π.χ. από 1 έως 100 σεντ).
`customer_reference`	Συμβολοσειρά	Ναι	Η αναφορά ελέγχου του συστήματός σας.
`allowed_origin`	Συμβολοσειρά	Ναι	Widget HTTPS πηγή.
`locale`	Συμβολοσειρά	Όχι	Γλώσσα widget (`es`).
`expected_mode`	Συμβολοσειρά	Όχι	Αναμενόμενη λειτουργία (`mock` ή `live`).

Όταν καθορίζεται profile, ο διακομιστής εκχωρεί αυτόματα τον επίσημο δικαιούχο πληρωμής και την αντίστοιχη ιδέα. Μην στέλνετε beneficiary ή reference για αιτήματα με διαχειριζόμενο προφίλ.

Κανόνας `Idempotency-Key`

Η κεφαλίδα Idempotency-Key απαιτείται σε κάθε κλήση δημιουργίας. Πρέπει να περιέχει από 16 έως 128 χαρακτήρες ορατού κειμένου ASCII, χωρίς κενά (για παράδειγμα, ένα UUID v4). Το πεδίο εφαρμογής του είναι μοναδικό για την εταιρεία που έχει υποβληθεί σε έλεγχο ταυτότητας:

Ίδιο κλειδί και ίδιο σώμα: Επιστρέφει την αρχική πρόθεση που δημιουργήθηκε προηγουμένως μαζί με idempotent_replay: true. Δεν δημιουργείται νέα χρέωση και η τραπεζική εντολή δεν αντιγράφεται.
Ίδιο κλειδί και διαφορετικό σώμα: απαντήστε αμέσως με HTTP 409 Conflict.
Το ίδιο κλειδί σε μια άλλη εταιρεία: ανήκει σε έναν άλλο εντελώς απομονωμένο χώρο idempotency.

Εάν μια κλήση δημιουργίας υποστεί διακοπή δικτύου ή λήξη χρονικού ορίου, δοκιμάστε ξανά με την ίδια ακριβώς κεφαλίδα Idempotency-Key και το ίδιο σώμα. Μην δημιουργήσετε νέο κλειδί σε περίπτωση παροδικής βλάβης.

Επιμονή και κύκλος ζωής

Προηγούμενη επιμονή: Η πρόθεση καταγράφεται στη βάση δεδομένων πριν από την επιστροφή της απάντησης ή την αλληλεπίδραση με οποιαδήποτε τραπεζική σύνδεση.
Εφήμερο διακριτικό widget: Το token απόκρισης (payment.widget.token) έχει σύντομη χρονική ισχύ (συνήθως 15 έως 30 λεπτά) και μπορεί να χρησιμοποιηθεί μόνο από τη δηλωμένη allowed_origin .
Κλείδωμα συγχρονισμού: Το σύστημα εφαρμόζει αισιόδοξο έλεγχο και μισθώσεις για να αποτρέψει δύο ταυτόχρονες κλήσεις από το να εξουσιοδοτήσουν ή να τροποποιήσουν την ίδια πρόθεση.

Κοινοί κωδικοί σφαλμάτων

HTTP	Κωδικός	Αιτία	Συνιστώμενη δράση
`400`	`idempotency_key_required`	Η κεφαλίδα `Idempotency-Key` λείπει ή δεν έχει μορφοποιηθεί σωστά.	Δημιουργήστε ένα έγκυρο κλειδί μεταξύ 16 και 128 χαρακτήρων ορατού κειμένου ASCII, χωρίς κενά.
`409`	`idempotency_conflict`	Το κλειδί έχει επαναχρησιμοποιηθεί με διαφορετικά στοιχεία πληρωμής.	Δημιουργήστε ένα νέο κλειδί για διαφορετικές πληρωμές ή επαναχρησιμοποιήστε το ίδιο σώμα.
`409`	`payment_mode_mismatch`	`expected_mode` δεν ταιριάζει με τη λειτουργία του περιβάλλοντος που καλείτε.	Ελέγξτε εάν στοχεύετε στο sandbox ή στην παραγωγή. η λειτουργία ορίζεται από την ανάπτυξη και όχι από την κλήση.
`401`	`invalid_api_key`	Η κεφαλίδα `X-API-Key`λείπει, η μορφή της δεν είναι έγκυρη ή το κλειδί πρόσβασης δεν υπάρχει ή είναι ανενεργό.	Ελέγξτε τον κωδικό πρόσβασης. Μην το συμπεριλάβετε ποτέ στο frontend.
`403`	`payments_not_allowed`	Το κλειδί API δεν έχει ενεργοποιημένο το `PAYMENTS` του προϊόντος.	Επικοινωνήστε με Wealth Reader υποστήριξη για να ενεργοποιήσετε τις πληρωμές στον λογαριασμό σας.
`403`	`payment_profile_not_allowed`	Το διαχειριζόμενο προφίλ δεν είναι ενεργοποιημένο για την εταιρεία σας.	Ζητήστε εγγραφή λογαριασμού προφίλ από Wealth Reader.
`429`	`api_limit_reached`	Ο κωδικός πρόσβασής σας έχει εξαντλήσει τον αθροιστικό μετρητή κλήσεων.	Δεν λύνεται με επανάληψη ή αναμονή: δεν υπάρχει παράθυρο ή αυτόματη επαναφορά. Αίτημα για παράταση του ορίου.
`415`	`json_required`	Λείπει η κεφαλίδα `Content-Type: application/json`.	Στείλτε το σώμα ως JSON.
`422`	`invalid_request`	Λείπει ένα απαιτούμενο πεδίο ή έχει υποβληθεί ένα μη αναγνωρισμένο πεδίο.	Ελέγξτε τον πίνακα παραμέτρων: το σώμα είναι μια αυστηρή λίστα επιτρεπόμενων.
`422`	`invalid_institution`	Η επιλεγμένη οντότητα δεν είναι διαθέσιμη ή δεν είναι έγκυρη.	Δείτε `GET /payments/entities/` για έγκυρους κωδικούς.
`422`	`invalid_amount`	Το ποσό είναι μικρότερο από το ελάχιστο (0,01 €) ή δεν είναι ακέραιος.	Βεβαιωθείτε ότι στέλνετε έναν ακέραιο αριθμό σε σεντ (`amount_minor`).

Επόμενο βήμα

Συνέχισε με Καταστάσεις, περιοδικός έλεγχος και συμφωνία πληρωμών.

Τελευταία ενημέρωση 2026-09-10