Οδηγός NBG Mastercard Gateway για WooCommerce

Οδηγός ρύθμισης: Εθνική Τράπεζα (NBG Mastercard Gateway) για WooCommerce

Ο οδηγός αφορά την έκδοση 1.0.3 του «OBS NBG Payment Gateway». Δεν αφορά το ξεχωριστό NBG Global Payments. Η OBS κάνει δωρεάν όλα τα παρακάτω βήματα για εσάς.

Τι χρειάζεστε πριν ξεκινήσετε

• Επιβεβαίωση από την Εθνική ότι ο λογαριασμός σας ανήκει στο NBG Mastercard Gateway και όχι στο Global Payments.
• Από το NBG Merchant Portal: δοκιμαστικό Merchant ID (ξεκινά με TEST) και API Password, παραγωγικό Merchant ID και API Password, Webhook Secret.
• Απόφαση για Purchase ή Authorize και για Hosted Checkout ή Hosted Session.
• WordPress 6.0+, WooCommerce 8.5+, PHP 7.4+ με cURL, HTTPS και ενεργό REST API.
• Πλήρες backup αρχείων και βάσης.

Βήμα 1: Εγκατάσταση και άδεια

1. Κατεβάστε το ZIP από τα «Downloads» του λογαριασμού σας στο obstechnologies.gr.
2. Στο WordPress ανοίξτε «Πρόσθετα» → «Προσθήκη νέου» → «Μεταφόρτωση πρόσθετου», ανεβάστε το ZIP και πατήστε «Ενεργοποίηση». Δείτε και τον γενικό οδηγό εγκατάστασης.
3. Το plugin δεν έχει πεδίο License key. Η άδεια και το domain διαχειρίζονται από τις «Άδειες χρήσης» του λογαριασμού σας (ενεργοποίηση άδειας).
4. Ανοίξτε «WooCommerce» → «Ρυθμίσεις» → «Πληρωμές» → «OBS NBG Payment Gateway». Κρατήστε τη μέθοδο ανενεργή μέχρι να τελειώσουν οι δοκιμές.

Βήμα 2: Χάρτης ρυθμίσεων

Βήμα 3: Δοκιμή σε sandbox

1. Με ενεργό το «Test Sandbox» και τα δοκιμαστικά στοιχεία, ενεργοποιήστε τη μέθοδο και κάντε μια παραγγελία με δοκιμαστική κάρτα της τράπεζας.
2. Επιτυχία: η παραγγελία γίνεται «Σε επεξεργασία» με σημείωση «CAPTURED» ή «AUTHORIZED», ID συναλλαγής και κωδικό έγκρισης.
3. Απόρριψη: η παραγγελία γίνεται «Αποτυχημένη» με σημείωση «Payment was declined.».
4. Ακύρωση και κλείσιμο του browser: η παραγγελία δεν σημειώνεται πληρωμένη χωρίς επιβεβαίωση της τράπεζας.
5. Σε «Authorize»: «Capture Authorized Amount» και «Void» από τις ενέργειες της παραγγελίας.
6. Ολική και μερική επιστροφή από την παραγγελία.
7. Τα ίδια σε κλασικό checkout και σε Checkout Blocks.

Go-live checklist

• Η Εθνική επιβεβαίωσε τον παραγωγικό λογαριασμό, τα νομίσματα και το integration model.
• Παραγωγικά Merchant ID και API Password περασμένα και «Test Sandbox» ανενεργό.
• Gateway «Custom URL» με host ibanke-commerce.nbg.gr.
• Webhook Secret συμπληρωμένο και /wp-json/obs-nbg/v1/webhook/ προσβάσιμο, χωρίς cache ή firewall.
• 3D Secure ρυθμισμένο σύμφωνα με τον λογαριασμό σας.
• Μια πραγματική πληρωμή μικρής αξίας συμφωνεί με το NBG Merchant Portal και επιστράφηκε.

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

• Σύμπτωμα: Στο checkout εμφανίζεται «No client found for the specified request».
  Αιτία: Το Custom Gateway Host περιέχει https:// ή http://, είναι λάθος host, ή το Checkout Interaction είναι «Embedded» σε λογαριασμό που δεν το υποστηρίζει.
  Λύση: Επιλέξτε Gateway «Custom URL», γράψτε μόνο ibanke-commerce.nbg.gr χωρίς πρόθεμα ή path και αλλάξτε το Checkout Interaction σε «Redirect to Payment Page».
• Σύμπτωμα: Η σελίδα πληρωμής της τράπεζας δείχνει «False» στη θέση του ονόματος της επιχείρησης.
  Αιτία: Είναι ενεργό το «Merchant Information Forwarding», αλλά το «Merchant Name» ή άλλο πεδίο της ενότητας Merchant Information είναι κενό ή άκυρο.
  Λύση: Συμπληρώστε σωστά το «Merchant Name» και τα υπόλοιπα πεδία ή απενεργοποιήστε το «Merchant Information Forwarding».
• Σύμπτωμα: Σφάλμα «INVALID_REQUEST: Value '' is invalid. Length is 0 characters…» στην πληρωμή.
  Αιτία: Με ενεργό το «Send Line Items», κάποιο προϊόν δεν έχει κωδικό (SKU) ή άλλο υποχρεωτικό στοιχείο. Σε παλαιότερες εκδόσεις το ίδιο σφάλμα εμφανιζόταν και με εκπτώσεις.
  Λύση: Συμπληρώστε SKU σε όλα τα προϊόντα ή απενεργοποιήστε το «Send Line Items», και ενημερώστε στην τελευταία έκδοση.
• Σύμπτωμα: Η πληρωμή απορρίπτεται όταν το ποσό έχει δεκαδικά ή όταν εφαρμόζεται κουπόνι ποσοστού.
  Αιτία: Παλαιότερες εκδόσεις έστελναν ποσά με ελληνικό δεκαδικό κόμμα ή με διαφορά στρογγυλοποίησης.
  Λύση: Ενημερώστε στην 1.0.3, που μορφοποιεί σωστά κάθε ποσό πριν το στείλει στην τράπεζα.
• Σύμπτωμα: Ο πελάτης πλήρωσε, αλλά η παραγγελία μένει «Εκκρεμεί πληρωμή».
  Αιτία: Δεν έφτασε η επιστροφή του πελάτη και το webhook απορρίφθηκε ή μπλοκαρίστηκε: κενό ή λάθος Webhook Secret, firewall, cache ή κλειστό REST API.
  Λύση: Συμπληρώστε το Webhook Secret από το NBG Merchant Portal, αφήστε ανοιχτό το /wp-json/obs-nbg/v1/webhook/ και επιβεβαιώστε τη συναλλαγή στο portal πριν εκτελέσετε την παραγγελία.
• Σύμπτωμα: Authentication error ή η σελίδα πληρωμής δεν ανοίγει καθόλου.
  Αιτία: Λάθος Merchant ID ή API Password, ή δοκιμαστικά στοιχεία ενώ το Test Sandbox είναι κλειστό (και το αντίστροφο).
  Λύση: Ελέγξτε ότι τα στοιχεία ανήκουν στο περιβάλλον που έχετε επιλέξει. Το δοκιμαστικό Merchant ID ξεκινά με TEST.
• Σύμπτωμα: Η μέθοδος πληρωμής δεν εμφανίζεται στο checkout.
  Αιτία: Λείπει Merchant ID ή API Password για το ενεργό περιβάλλον (sandbox ή live), ή η μέθοδος δεν είναι ενεργή.
  Λύση: Συμπληρώστε τα στοιχεία του περιβάλλοντος που χρησιμοποιείτε και τσεκάρετε το «Enable/Disable».
• Σύμπτωμα: Δεν εμφανίζονται οι ενέργειες «Capture Authorized Amount» και «Void».
  Αιτία: Εμφανίζονται μόνο σε παραγγελίες του gateway που είναι «Σε επεξεργασία» και δεν έχουν ήδη χρεωθεί, δηλαδή σε Transaction Mode «Authorize».
  Λύση: Ελέγξτε το Transaction Mode και την κατάσταση της παραγγελίας. Σε «Purchase» η χρέωση γίνεται αμέσως.
• Σύμπτωμα: Οι σύνδεσμοι «Docs» και «Support» στη λίστα προσθέτων ή ο σύνδεσμος για τα API credentials βγάζουν «Page Not Found».
  Αιτία: Παραπέμπουν σε παλιές διευθύνσεις.
  Λύση: Χρησιμοποιήστε τον οδηγό στο /docs/setup-nbg-mastercard-gateway-woocommerce και πάρτε τα στοιχεία από το NBG Merchant Portal.
• Σύμπτωμα: Η τράπεζα δείχνει «Sorry, but we are unable to complete your payment… Support code».
  Αιτία: Το αίτημα απορρίφθηκε από την πύλη της τράπεζας, συχνά λόγω ρύθμισης στον λογαριασμό ή στο ποσό.
  Λύση: Στείλτε στην Εθνική τον Support code και την ώρα της απόπειρας, και ενημερώστε το plugin στην τελευταία έκδοση.

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