Οδηγός Alpha Bank e-Commerce για WooCommerce

Οδηγός ρύθμισης Alpha Bank e-Commerce για WooCommerce

Ο οδηγός αφορά την έκδοση 2.0.0 του WooCommerce Alpha Bank e-Commerce Plugin (ροή Cardlink). Αν θέλετε, η OBS Technologies κάνει όλη τη ρύθμιση δωρεάν.

Προαπαιτούμενα

• Υπογεγραμμένη σύμβαση e-commerce με την Alpha Bank και, αν θέλετε δόσεις, έγκριση δόσεων.
• Δοκιμαστικά (sandbox) στοιχεία από την τράπεζα/Cardlink: Merchant ID, Shared Secret και το HTTPS endpoint (Form Post URL). Αργότερα θα λάβετε και τα αντίστοιχα παραγωγικά.
• WordPress με WooCommerce, PHP 7.4 ή νεότερη και ενεργό SSL σε όλο το site.
• Πλήρες backup αρχείων και βάσης δεδομένων πριν από την εγκατάσταση ή την αναβάθμιση.

Εγκατάσταση και License key

1. Κατεβάστε το ZIP του πρόσθετου και το License key από τον λογαριασμό σας στο obstechnologies.gr.
2. Στο WordPress πηγαίνετε Πρόσθετα → Προσθήκη νέου → Μεταφόρτωση πρόσθετου, επιλέξτε το ZIP και πατήστε Εγκατάσταση και μετά Ενεργοποίηση.
3. Ενεργοποιήστε το License key για το domain σας, όπως περιγράφεται στον οδηγό Ενεργοποίηση άδειας. Το key ενεργοποιείται για ένα ηλεκτρονικό κατάστημα.
4. Ανοίξτε WooCommerce → Ρυθμίσεις → Πληρωμές → Alpha Bank e-Commerce.

Χάρτης ρυθμίσεων

• Enable/Disable («Enable Cardlink Payments»): ενεργοποιεί τη μέθοδο. Κρατήστε την ανενεργή στο live site μέχρι να ολοκληρωθούν οι δοκιμές.
• Title: ο τίτλος που βλέπει ο πελάτης στο checkout (προεπιλογή «Alphabank Payments»). Προτείνουμε κάτι σαν «Πληρωμή με κάρτα».
• Plugin Description: το κείμενο κάτω από τον τίτλο. Η προεπιλογή αναφέρει κάρτες Visa, Mastercard, Maestro, American Express και Diners.
• Cardlink Form Post Url: το HTTPS endpoint πληρωμής που σας έδωσε η Alpha Bank/Cardlink, το δοκιμαστικό για τις δοκιμές και το παραγωγικό για το live. Πρέπει να ξεκινά με https://, αλλιώς η μέθοδος δεν εμφανίζεται. Η προεπιλεγμένη τιμή είναι demo και πρέπει πάντα να αντικατασταθεί.
• Cardlink Merchant ID: το Merchant ID του περιβάλλοντος που χρησιμοποιείτε.
• Cardlink Shared Secret Key: το μυστικό κλειδί για την υπογραφή (digest) των αιτημάτων και των απαντήσεων. Μην το στέλνετε σε email, ticket ή screenshot.
• Installment ranges: κανόνες δόσεων στη μορφή ελάχιστο@μέγιστο@δόσεις, χωρισμένους με |, π.χ. 0@100@3|100@500@6. Ο κανόνας ισχύει για σύνολο καλαθιού μεγαλύτερο από το ελάχιστο και έως το μέγιστο. Οι δόσεις περιορίζονται σε 1–36 και δεν πρέπει να ξεπερνούν όσες έχει εγκρίνει η τράπεζα. Αφήστε το κενό για πληρωμή χωρίς δόσεις.
• Enable debug: καταγράφει μόνο την κατάσταση και τη διαθεσιμότητα των πεδίων κάθε απάντησης (πηγή obs-alpha-bank), χωρίς κωδικούς. Ενεργοποιήστε το μόνο όταν διερευνάτε κάποιο πρόβλημα.

Το URL επιστροφής που στέλνει το plugin στην τράπεζα για επιβεβαίωση και ακύρωση είναι https://το-domain-σας/wc-api/WC_Gateway_Alpha_Cardlink/. Πρέπει να είναι προσβάσιμο μέσω HTTPS, χωρίς cache, κωδικό πρόσβασης ή maintenance mode.

Δοκιμή (sandbox)

Το plugin δεν έχει ξεχωριστό διακόπτη «test mode». Η δοκιμή γίνεται με το δοκιμαστικό endpoint και τα sandbox Merchant ID/Shared Secret της τράπεζας, ιδανικά σε staging αντίγραφο του eshop.

1. Κάντε μια μικρή παραγγελία χωρίς δόσεις και ολοκληρώστε την πληρωμή με δοκιμαστική κάρτα. Η παραγγελία πρέπει να γίνει πληρωμένη μία φορά, με σημείωση και transaction ID.
2. Κάντε μία παραγγελία με τον μέγιστο αριθμό δόσεων της κλίμακας.
3. Δοκιμάστε απόρριψη και ακύρωση από τη σελίδα της τράπεζας. Η παραγγελία πρέπει να γίνει «Αποτυχημένη» και να μη σημειωθεί ως πληρωμένη.
4. Επαναλάβετε τις δοκιμές και στο κλασικό checkout και στα Checkout Blocks, αν χρησιμοποιείτε και τα δύο.
5. Ανανεώστε τη σελίδα επιστροφής. Δεν πρέπει να δημιουργηθεί διπλή πληρωμή ή διπλή σημείωση.

Go-live checklist

• Η τράπεζα έχει επιβεβαιώσει την ολοκλήρωση των δοκιμών και έχει εκδώσει παραγωγικά στοιχεία.
• Έχετε αντικαταστήσει endpoint, Merchant ID και Shared Secret με τα παραγωγικά. Μην αντιγράφετε στοιχεία από άλλο gateway ή περιβάλλον.
• Οι κλίμακες δόσεων συμφωνούν με τη σύμβασή σας.
• Το Enable debug είναι απενεργοποιημένο.
• Το /wc-api/WC_Gateway_Alpha_Cardlink/ έχει εξαιρεθεί από cache και firewall.
• Κάνατε μία μικρή πραγματική συναλλαγή και την επιστρέψατε από το back office της τράπεζας.

Αντιμετώπιση προβλημάτων

• Πατώντας «Ολοκλήρωση παραγγελίας» δεν γίνεται ανακατεύθυνση, ή ο browser δείχνει «This site can’t be reached» / DNS error.
  Αιτία: Λάθος, ελλιπές ή παλιό Cardlink Form Post Url (τυπογραφικό λάθος, endpoint που άλλαξε από την τράπεζα ή η demo προεπιλογή). Σπανιότερα, plugin ασφαλείας ή cache που μπλοκάρει τη σελίδα ανακατεύθυνσης.
  Λύση: Περάστε ακριβώς το endpoint που σας έδωσε η τράπεζα για το περιβάλλον σας, με https://, καθαρίστε την cache και δοκιμάστε ξανά. Αν η τράπεζα σας έχει μεταφέρει σε Nexi XPay, χρειάζεστε το αντίστοιχο plugin.
• Τα στοιχεία που έδωσε η τράπεζα (π.χ. API Key terminal του Nexi merchant portal) δεν ταιριάζουν με τα πεδία του plugin.
  Αιτία: Τα στοιχεία είναι για το περιβάλλον Nexi XPay και όχι για τη ροή Cardlink (Merchant ID και Shared Secret).
  Λύση: Χρησιμοποιήστε το WooCommerce Alpha Bank X Pay (Nexi XPay) ή ζητήστε από την τράπεζα στοιχεία Cardlink. Η OBS μπορεί να σας βοηθήσει να καταλάβετε ποια στοιχεία έχετε.
• Η μέθοδος Alpha Bank δεν εμφανίζεται στο checkout.
  Αιτία: Λείπει το Merchant ID ή το Shared Secret, ή το Form Post Url δεν ξεκινά με https://. Σε αυτές τις περιπτώσεις το plugin κρύβει τη μέθοδο.
  Λύση: Συμπληρώστε και τα τρία πεδία με στοιχεία του ίδιου περιβάλλοντος, με endpoint HTTPS, και βεβαιωθείτε ότι το Enable/Disable είναι ενεργό.
• Η τράπεζα δείχνει επιτυχημένη πληρωμή, αλλά η παραγγελία μένει «Σε αναμονή πληρωμής».
  Αιτία: Η απάντηση της τράπεζας δεν έφτασε στο /wc-api/WC_Gateway_Alpha_Cardlink/ (cache, WAF, maintenance mode, πρόβλημα SSL) ή απορρίφθηκε στον έλεγχο.
  Λύση: Εξαιρέστε το URL από cache και firewall, ελέγξτε το πιστοποιητικό SSL και ενεργοποιήστε προσωρινά το debug. Μην σημειώνετε την παραγγελία ως πληρωμένη πριν τη βρείτε στο back office της τράπεζας.
• Στο log εμφανίζεται «Rejected callback authentication» (λάθος digest).
  Αιτία: Το Shared Secret δεν αντιστοιχεί στο περιβάλλον του endpoint, π.χ. sandbox κλειδί με παραγωγικό endpoint.
  Λύση: Περάστε ξανά το Shared Secret του σωστού περιβάλλοντος, χωρίς κενά στην αρχή ή στο τέλος, και κάντε νέα δοκιμή.
• Στο log εμφανίζεται «Rejected callback binding».
  Αιτία: Το ποσό, το νόμισμα, το Merchant ID ή η αναφορά της απάντησης δεν ταιριάζουν με την παραγγελία, π.χ. αλλαγή συνόλου μετά την ανακατεύθυνση ή λάθος Merchant ID.
  Λύση: Μην εκτελέσετε την παραγγελία. Συγκρίνετε με το back office της τράπεζας και, αν χρειάζεται, ζητήστε από τον πελάτη νέα πληρωμή.
• Η παραγγελία μπήκε «Σε αναμονή» με σημείωση ότι η πληρωμή είναι εγκεκριμένη αλλά όχι χρεωμένη.
  Αιτία: Η τράπεζα απάντησε AUTHORIZED (προέγκριση) αντί για CAPTURED. Το plugin δεν ολοκληρώνει αυτόματα τις προεγκρίσεις.
  Λύση: Ελέγξτε τη συναλλαγή στο back office της τράπεζας, ολοκληρώστε ή ακυρώστε την εκεί και ενημερώστε χειροκίνητα την παραγγελία.
• Δεν εμφανίζεται επιλογή δόσεων.
  Αιτία: Το σύνολο του καλαθιού δεν πέφτει σε κανέναν κανόνα, ή ο κανόνας έχει λάθος μορφή και αγνοείται.
  Λύση: Ελέγξτε τη μορφή ελάχιστο@μέγιστο@δόσεις και το «|» ανάμεσα στους κανόνες, π.χ. 0@100@3|100@500@6. Θυμηθείτε ότι το ελάχιστο δεν περιλαμβάνεται στο εύρος.
• Μήνυμα «Invalid installment selection» στο checkout.
  Αιτία: Ο αριθμός δόσεων που στάλθηκε είναι μεγαλύτερος από όσο επιτρέπει ο κανόνας για το τρέχον σύνολο, π.χ. αλλαγή καλαθιού μετά την επιλογή.
  Λύση: Ο πελάτης ανανεώνει τη σελίδα και ξαναεπιλέγει δόσεις. Αν συμβαίνει συχνά, ελέγξτε για cache στη σελίδα checkout.
• Το κλασικό checkout λειτουργεί, αλλά τα Checkout Blocks όχι (ή το αντίστροφο).
  Αιτία: Παλιά αρχεία JavaScript στην cache ή σύγκρουση με το theme ή άλλο plugin.
  Λύση: Καθαρίστε την cache του site και του browser, βεβαιωθείτε ότι φορτώνει η τρέχουσα έκδοση του plugin και δοκιμάστε με standard WooCommerce theme.
• Πληρωμές με δόσεις απορρίπτονται, ενώ εφάπαξ πληρωμές περνούν.
  Αιτία: Οι δόσεις δεν είναι ενεργοποιημένες στο Merchant ID, ή ο αριθμός δόσεων στην κλίμακα ξεπερνά αυτόν που έχει εγκρίνει η τράπεζα.
  Λύση: Επιβεβαιώστε με την Alpha Bank τις εγκεκριμένες δόσεις και προσαρμόστε το Installment ranges ώστε να μην τις ξεπερνά.
• Δεν εμφανίζεται διαθέσιμη ενημέρωση στο WordPress, ή εμφανίζονται PHP warnings/errors από το plugin.
  Αιτία: Τρέχει παλιά έκδοση (π.χ. 1.6.x), που δεν ενημερώνεται αυτόματα από το WordPress, σε νεότερη PHP.
  Λύση: Πάρτε το τρέχον ZIP από την OBS, κρατήστε backup, ανεβάστε το και επαναλάβετε μια δοκιμαστική πληρωμή.