Οδηγός Nexi XPay για WooCommerce

Οδηγός ρύθμισης Nexi XPay (Alpha Bank X Pay) για WooCommerce

Ο οδηγός αφορά την έκδοση 2.1.x του plugin «OBS Nexi XPay for WooCommerce». Αν θέλετε, η OBS Technologies κάνει όλη τη ρύθμιση δωρεάν.

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

• Σύμβαση e-commerce με την Alpha Bank / Nexi Greece και πρόσβαση στο Nexi merchant portal (Nexi XPay Admin Tool).
• API Key για το sandbox και αργότερα για το live. Μάθετε επίσης από τη Nexi αν το terminal κάνει implicit (άμεση) ή explicit (προέγκριση) χρέωση και αν έχουν ενεργοποιηθεί δόσεις (και πόσες) και IRIS.
• WordPress 5.8+, WooCommerce 6.0+, PHP 7.4+, SSL, ενεργό WordPress REST API και WP-Cron.
• Backup αρχείων και βάσης. Αν έχετε παλαιότερη έκδοση του plugin, μην την απεγκαταστήσετε: η αναβάθμιση κρατά τις ρυθμίσεις.

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

1. Κατεβάστε το ZIP και το License key από τον λογαριασμό σας στο obstechnologies.gr.
2. Πρόσθετα → Προσθήκη νέου → Μεταφόρτωση πρόσθετου, επιλέξτε το ZIP, Εγκατάσταση και μετά Ενεργοποίηση του «OBS Nexi XPay for WooCommerce».
3. Ενεργοποιήστε το License key για το domain σας, όπως περιγράφεται στην Ενεργοποίηση άδειας.
4. Ανοίξτε WooCommerce → Ρυθμίσεις → Πληρωμές → Nexi XPay.

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

Γενικά

• Enable/Disable («Enable Nexi XPay»): ενεργοποίηση της μεθόδου.
• Title / Description: το κείμενο στο checkout. Οι προεπιλογές είναι «Credit/Debit Card» και «Secure payment via Nexi XPay». Η Nexi συνήθως ζητά να αναφέρεται ρητά το Nexi XPay.
• API Key: το κλειδί από το Nexi merchant portal. Δεν απαιτείται shared secret ή URL ειδοποιήσεων, γιατί το plugin δημιουργεί μόνο του ασφαλές URL ανά παραγγελία.
• Test Mode («Enable sandbox environment»): στέλνει τις συναλλαγές στο sandbox της Nexi.
• Debug Log («Enable logging (redacted)»): logs χωρίς κωδικούς ή στοιχεία καρτών, πηγή obs-nexi-xpay.

Greek Installments

• Enable installments: εμφάνιση δόσεων στο checkout. Απαιτεί ελληνικό terminal με ενεργό πρόγραμμα ACQUIRER_AGREEMENT.
• Maximum installments: το απόλυτο μέγιστο (1 = χωρίς δόσεις). Ορίστε το σύμφωνα με τη σύμβασή σας.
• Installment amount ranges: προαιρετικά όρια σε JSON, π.χ. [{"amount":100,"installments":6},{"amount":500,"installments":12}]. Για κάθε σύνολο ισχύει το υψηλότερο όριο που καλύπτεται, πάντα μέσα στο μέγιστο.

OBS Installment Pricing Rules

• Single-payment discount (%): έκπτωση όταν ο πελάτης πληρώνει εφάπαξ.
• Installment surcharge rates: ποσοστό επιβάρυνσης ανά αριθμό δόσεων. Ο πίνακας δείχνει γραμμές έως το μέγιστο, οπότε αποθηκεύστε για να ανανεωθεί.
• Excluded product categories: slugs κατηγοριών, χωρισμένα με κόμμα, που εξαιρούνται από έκπτωση και επιβάρυνση.
• Product-page estimate: προαιρετική, ενημερωτική εκτίμηση δόσεων στη σελίδα προϊόντος. Η τελική επιλογή γίνεται στο checkout.

IRIS Payment

• Enable IRIS: εμφανίζει το IRIS ως αποδεκτή μέθοδο στο checkout.
• IRIS as default: προεπιλέγει το IRIS στη σελίδα πληρωμής της Nexi.

Δοκιμή (Test Mode)

1. Ενεργοποιήστε το Test Mode με το sandbox API Key και κάντε μια μικρή παραγγελία με τις δοκιμαστικές κάρτες της Nexi. Η παραγγελία πρέπει να γίνει «Σε επεξεργασία» με σημείωση αποτελέσματος.
2. Δοκιμάστε απόρριψη και ακύρωση από τη σελίδα πληρωμής. Πρέπει να καταλήξουν «Αποτυχημένη» και «Ακυρωμένη» αντίστοιχα.
3. Δοκιμάστε πληρωμή με τον μέγιστο αριθμό δόσεων, σε κλασικό checkout και σε Blocks.
4. Κάντε ολική και μερική επιστροφή από την παραγγελία. Σε explicit terminal δοκιμάστε επίσης τις ενέργειες «Capture Nexi authorisation» και «Void Nexi authorisation».
5. Αν έχετε IRIS, ελέγξτε ότι εμφανίζεται στη σελίδα της Nexi. Η ροή QR στο sandbox της Nexi μπορεί να μην ολοκληρώνεται.

Go-live checklist

• Η Nexi ολοκλήρωσε τον έλεγχο του site: εμφανίζεται ο τρόπος πληρωμής Nexi XPay, υπάρχουν τα λογότυπα καρτών και οι όροι πληρωμής και ασφάλειας είναι ενημερωμένοι.
• Έχετε αντικαταστήσει μόνο το API Key με το live και απενεργοποιήσει το Test Mode. Μη χρησιμοποιείτε ποτέ δημοσιευμένα sandbox κλειδιά στο live.
• Το μέγιστο των δόσεων και οι επιβαρύνσεις συμφωνούν με τη σύμβαση.
• Το REST API, το WP-Cron και τα loopback requests λειτουργούν (Εργαλεία → Υγεία ιστότοπου).
• Κάνατε μια μικρή πραγματική συναλλαγή και τη συμφωνήσατε με το Nexi portal. Το Debug Log είναι κλειστό.

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

• Τα στοιχεία της τράπεζας είναι Merchant ID, Shared Secret και Form Post Url, ενώ το plugin ζητά API Key.
  Αιτία: Η σύμβασή σας είναι στην παλαιότερη ροή Alpha Bank e-Commerce μέσω Cardlink και όχι στη Nexi XPay.
  Λύση: Χρησιμοποιήστε το WooCommerce Alpha Bank e-Commerce Plugin, ή ζητήστε από την τράπεζα ενεργοποίηση Nexi XPay και API Key.
• Η τράπεζα ενημέρωσε για μετάβαση σε Nexi XPay και το eshop τρέχει ακόμη το παλιό Alpha/Cardlink gateway.
  Αιτία: Αλλάζει ο επεξεργαστής. Τα παλιά στοιχεία δεν ισχύουν στο νέο περιβάλλον και δεν υπάρχει μεταφορά μισοτελειωμένων πληρωμών.
  Λύση: Εγκαταστήστε το Nexi XPay plugin με το νέο API Key. Οι κλίμακες δόσεων του παλιού gateway μεταφέρονται αυτόματα όπου αναγνωρίζονται, αλλιώς ρυθμίζονται χειροκίνητα. Όσες πληρωμές είχαν ξεκινήσει στο παλιό gateway, ο πελάτης τις ξαναξεκινά.
• Η Nexi δεν εγκρίνει το site για live και ζητά αλλαγές.
  Αιτία: Ο έλεγχος της Nexi απαιτεί σαφή αναφορά στο Nexi XPay ως τρόπο πληρωμής, λογότυπα των αποδεκτών καρτών και ενημερωμένους όρους πληρωμής και ασφάλειας.
  Λύση: Αλλάξτε το Title/Description ώστε να αναφέρει το Nexi XPay και αφαιρέστε παλιές αναφορές σε άλλο σύστημα πληρωμών. Από την 2.1.3 το checkout δείχνει το επίσημο banner καρτών Nexi. Ενημερώστε και τη σελίδα όρων.
• Δοκιμαστικές ή πραγματικές συναλλαγές απορρίπτονται με «Transaction Declined».
  Αιτία: Στο sandbox συνήθως χρησιμοποιείται κάρτα που δεν είναι από τις δοκιμαστικές της Nexi. Στο live η απόρριψη έρχεται συνήθως από τον εκδότη της κάρτας (π.χ. αποτυχία 3D Secure) και όχι από το plugin.
  Λύση: Στο sandbox χρησιμοποιήστε τις δοκιμαστικές κάρτες της Nexi. Στο live ελέγξτε τον λόγο απόρριψης στο Nexi portal και ζητήστε από τον πελάτη να επικοινωνήσει με την τράπεζά του ή να δοκιμάσει άλλη κάρτα.
• Απορρίψεις όταν ο πελάτης γράφει το όνομα κατόχου με τελείες ή σύμβολα.
  Αιτία: Το πεδίο ονόματος κατόχου συμπληρώνεται στη σελίδα πληρωμής της Nexi και ορισμένα σύμβολα μπορεί να οδηγήσουν σε απόρριψη.
  Λύση: Ζητήστε από τον πελάτη να γράψει το όνομα όπως είναι τυπωμένο στην κάρτα, χωρίς τελείες ή σύμβολα, και να ξαναδοκιμάσει.
• Ο πελάτης πλήρωσε, αλλά η παραγγελία μένει «Σε αναμονή πληρωμής».
  Αιτία: Η ειδοποίηση της Nexi δεν έφτασε στο REST route του plugin (απενεργοποιημένο REST API, firewall/WAF, maintenance mode, προστασία με κωδικό) ή η Nexi δεν έχει ακόμη τελική κατάσταση.
  Λύση: Βεβαιωθείτε ότι το /wp-json/obs-nexi-xpay/v1/ είναι προσβάσιμο από το internet και ότι λειτουργούν τα loopback requests και το WP-Cron. Ελέγξτε τη συναλλαγή στο Nexi portal πριν εκτελέσετε την παραγγελία.
• Η παραγγελία μπήκε «Σε αναμονή» με σημείωση «amount/currency mismatch».
  Αιτία: Το ποσό ή το νόμισμα της Nexi δεν ταιριάζει με την παραγγελία, π.χ. αλλαγή συνόλου μετά την ανακατεύθυνση.
  Λύση: Μην εκτελέσετε την παραγγελία. Συγκρίνετε με το Nexi portal και κάντε επιστροφή ή ζητήστε νέα πληρωμή.
• Δεν εμφανίζονται οι ενέργειες Capture/Void στην παραγγελία.
  Αιτία: Το terminal κάνει άμεση (implicit) χρέωση ή η παραγγελία δεν έχει αναφορά Nexi.
  Λύση: Σε implicit terminal δεν χρειάζεται capture και η επιστροφή γίνεται με refund. Για explicit χρέωση ζητήστε από τη Nexi το αντίστοιχο terminal και API Key.
• Δεν εμφανίζονται δόσεις στο checkout.
  Αιτία: Το Enable installments είναι κλειστό, το Maximum installments είναι 1, το σύνολο δεν καλύπτει κανένα όριο ή το JSON των ορίων δεν είναι έγκυρο.
  Λύση: Ελέγξτε τις τρεις ρυθμίσεις και τη μορφή του JSON. Αν το terminal δεν έχει δόσεις, η Nexi θα απορρίψει την πληρωμή με δόσεις.
• Το IRIS δεν εμφανίζεται ή η πληρωμή IRIS αποτυγχάνει.
  Αιτία: Το IRIS δεν είναι ενεργό στο Nexi terminal ή δεν έχει ενεργοποιηθεί το Enable IRIS. Στο sandbox η ροή QR της Nexi μπορεί να αποτυγχάνει.
  Λύση: Ζητήστε από την τράπεζα / Nexi ενεργοποίηση IRIS στο terminal, ενεργοποιήστε το Enable IRIS και δοκιμάστε με μικρό ποσό στο live.