Μηχανική πληρωμών / 01

Webhooks πληρωμών στο WooCommerce: σχεδίασε και τη δεύτερη παράδοση

Πρακτικός οδηγός για επαληθευμένα συμβάντα πληρωμών, διπλές παραδόσεις και ασφαλή ανάκτηση, με λίστα ελέγχου για WooCommerce gateways.

Από το WideDock · Wideview EntertainmentΔημοσιεύθηκε 6 λεπτά ανάγνωσης

Ένα webhook πληρωμής μεταφέρει ένα συμβάν του παρόχου. Δεν πρέπει να αλλάζει τυφλά την παραγγελία. Επαλήθευσε την προέλευσή του, αποθήκευσέ το αξιόπιστα, έλεγξε την πληρωμή και κάνε την επεξεργασία επαναλήψιμη. Η επιστροφή του πελάτη στο κατάστημα δεν αποτελεί απόδειξη είσπραξης.

Μία αγορά, τρεις ανεξάρτητες χρονικές διαδρομές

Ένας πελάτης ολοκληρώνει την πληρωμή με κάρτα, κλείνει την καρτέλα και επικοινωνεί αμέσως με το κατάστημα επειδή η παραγγελία φαίνεται ακόμη σε αναμονή. Υπάρχουν τουλάχιστον τρεις χρονικές διαδρομές: η πλοήγηση στον browser, οι εγγραφές του παρόχου και το ιστορικό της παραγγελίας. Μπορούν να διαφέρουν προσωρινά χωρίς να σημαίνει ότι κάποιο σύστημα έχει απαραίτητα χαλάσει. Η διασύνδεση πρέπει να τις συμφιλιώνει.

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

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

Έλεγξε χωριστά τον αποστολέα και την πληρωμή

Το πρώτο όριο είναι ο τεκμηριωμένος μηχανισμός ταυτοποίησης του παρόχου. Σε υπογεγραμμένο webhook χρησιμοποιούμε ακριβώς την αναπαράσταση του αιτήματος που απαιτεί ο πάροχος. Για παράδειγμα, η Stripe τεκμηριώνει επαλήθευση υπογραφής πάνω στο αρχικό σώμα του αιτήματος. Αν πρώτα διαβάσουμε το JSON και το δημιουργήσουμε ξανά, ενδέχεται να αλλάξουμε τα bytes που ελέγχονται.

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

Ο διαχωρισμός αυτός είναι ιδιαίτερα χρήσιμος όταν κατά την ανάπτυξη υπάρχουν test και live διαπιστευτήρια. Ένα σωστά υπογεγραμμένο δοκιμαστικό συμβάν δεν επιτρέπεται να θεωρηθεί πραγματική αγορά. Ομοίως, πληρωμή άλλου λογαριασμού δεν εξοφλεί μια άσχετη παραγγελία επειδή αναγνωρίζουμε ένα ID. Ταυτότητα, περιβάλλον και οικονομική αντιστοίχιση χρειάζονται ρητούς ελέγχους.

Αποθήκευσε την παραλαβή πριν την επιβεβαιώσεις

Ένα σύντομο webhook request είναι ευκολότερο στη λειτουργία από ένα αίτημα που ταυτόχρονα στέλνει email, παραδίδει πρόσβαση και πραγματοποιεί αργές εξωτερικές κλήσεις. Προτιμούμε μια εγγραφή εισερχόμενου συμβάντος και μια αξιόπιστα αποθηκευμένη εργασία για την επεξεργασία. Η επιβεβαίωση τότε σημαίνει ότι το συμβάν μπήκε σε διαδρομή από την οποία μπορεί να ανακτηθεί.

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

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

Η δεύτερη παράδοση πρέπει να είναι συνηθισμένη περίπτωση

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

Ο εντοπισμός διπλών συμβάντων και η επαναληψιμότητα οικονομικών ενεργειών λύνουν συγγενικά αλλά διαφορετικά προβλήματα. Δύο παραδόσεις του ίδιου συμβάντος μοιράζονται ένα event ID. Δύο διαφορετικά συμβάντα μπορεί να περιγράφουν την ίδια οικονομική μεταβολή. Γι’ αυτό απαιτείται σταθερή ταυτότητα πληρωμής, πέρα από την ταυτότητα του webhook. Το ίδιο εισπραγμένο ποσό δεν πρέπει να προκαλεί δεύτερη παράδοση προϊόντος.

Μια πρακτική αμετάβλητη συνθήκη δοκιμής είναι να επαναλάβουμε την ίδια επιβεβαιωμένη πληρωμή αρκετές φορές και να συγκρίνουμε παραγγελία, απόθεμα και παράδοση. Το τελικό αποτέλεσμα πρέπει να παραμένει σταθερό. Δεν αρκεί να κοιτάμε τον HTTP κωδικό. Εξετάζουμε τις πραγματικές εγγραφές που μπορούν να επηρεάσουν τον πελάτη ή τη λογιστική εικόνα του εμπόρου.

Επεξεργάσου την οικονομική κατάσταση, όχι τη σειρά άφιξης

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

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

Επιστροφές και αμφισβητήσεις απαιτούν δικό τους μοντέλο. Μια μερική επιστροφή δεν σημαίνει αυτομάτως πλήρη ακύρωση, ενώ ένα μεταγενέστερο συμβάν επιτυχίας δεν πρέπει να σβήνει οριστική επιστροφή. Κάθε προσαρμογή αντιστοιχίζεται στη σχετική πληρωμή και ποσό. Όταν υπάρχει ασάφεια, τη δείχνουμε στον χειριστή αντί να μαντεύουμε ποια γραμμή παραγγελίας ή ποιο δικαίωμα αλλάζει.

Σχεδίασε την ανάκτηση πριν τη χρειαστείς

Τα webhooks είναι σημαντική είσοδος, όμως το κατάστημα πρέπει να μπορεί να επανελέγξει μια παραγγελία στον πάροχο όταν μια παράδοση χαθεί ή η επεξεργασία μείνει αβέβαιη. Ο επανέλεγχος χρειάζεται τους ίδιους επαληθευμένους κανόνες μετάβασης. Ένα ξεχωριστό repair script που ερμηνεύει διαφορετικά την εξόφληση δημιουργεί δεύτερη πηγή αλήθειας.

Οι επαναλήψεις χρειάζονται όρια, σταδιακή αναμονή και ορατή τελική κατάσταση. Μια εργασία που αποτυγχάνει επ’ αόριστον μπορεί να κρύβει λειτουργικό περιστατικό. Ένας handler που εγκαταλείπει σιωπηλά χάνει την ευκαιρία ανάκτησης. Ο διαχειριστής πρέπει να διακρίνει προσωρινό πρόβλημα δικτύου, οριστικά άκυρο συμβάν και οικονομική ασυμφωνία που χρειάζεται ανθρώπινη απόφαση.

Η παρατηρησιμότητα δεν απαιτεί να αποθηκεύουμε για πάντα κάθε πλήρες request. Κρατάμε αναγνωριστικά, χρονικές σημάνσεις, κωδικούς αιτίας και όσα στοιχεία χρειάζονται για να εξηγηθεί η μετάβαση. Περιορίζουμε την πρόσβαση και δεν γράφουμε εξαρχής στοιχεία καρτών, credentials ή πλήρη προσωπικά δεδομένα στα logs. Η διάγνωση πρέπει να ακολουθεί την παραγγελία, όχι να δημιουργεί δεύτερη βάση πελατών.

Δοκίμασε μια ιστορία, όχι μόνο ένα endpoint

Μια ουσιαστική δοκιμή ξεκινά από συγκεκριμένη ιστορία πελάτη. Ολοκλήρωσε πληρωμή χωρίς επιστροφή στο κατάστημα. Παράδωσε δύο φορές την επιβεβαίωση. Διέκοψε τον worker μετά την παραλαβή αλλά πριν την παράδοση. Επανάλαβε μετά από timeout. Έπειτα κοίτα την παραγγελία και το ιστορικό της. Έτσι αποκαλύπτονται υποθέσεις που μια απλή επιτυχής δοκιμή browser δεν εξετάζει.

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

Για το VivaGo αυτά αποτελούν αρχές ανάπτυξης και σενάρια αποδοχής, όχι δήλωση ότι το μη διαθέσιμο ακόμη plugin υποστηρίζει κάθε συμβάν ή συνδυασμό WooCommerce. Το VivaGo παραμένει σε ανάπτυξη. Η δοκιμασμένη συμβατότητα και οι ακριβείς ροές πληρωμών θα δημοσιευθούν με την ελεγμένη έκδοση. Το χρήσιμο σήμερα είναι να ενσωματώνουμε τη διπλή παράδοση και τη διακοπή εργασίας στον σχεδιασμό από την αρχή.

Σύντομη λίστα αποδοχής webhooks

  • Το URL επιστροφής δεν αρκεί για εξόφληση παραγγελίας.
  • Ελέγχονται προέλευση, λογαριασμός, περιβάλλον, ποσό και νόμισμα.
  • Παραλαβή και εργασία έχουν κοινό αξιόπιστο όριο αποθήκευσης.
  • Επαναλήψεις δεν διπλασιάζουν οικονομικές ενέργειες ή παραδόσεις.
  • Παλιότερα συμβάντα δεν αντικαθιστούν τυφλά επαληθευμένη κατάσταση.
  • Υπάρχει τεκμηριωμένη διαδρομή επανελέγχου χαμένων παραδόσεων.
  • Η διάγνωση αποτυχιών δεν αποκαλύπτει μυστικά.

Πηγές και περαιτέρω ανάγνωση

Σχετικά με το άρθρο

Συντάχθηκε με υποβοήθηση AI και ελέγχθηκε σε σχέση με τη συνδεδεμένη τεχνική τεκμηρίωση. Τα άρθρα εξηγούν την προσέγγιση ανάπτυξής μας. Δεν αντικαθιστούν τεκμηρίωση ή εμπορικούς όρους διαθέσιμου προϊόντος. Επικοινώνησε για κάποια διόρθωση.

Πρότεινε διόρθωση

Συνέχισε την ανάγνωση

Γνώρισε το VivaGo · Τεκμηρίωση