Οδηγός χρήσης για διαχειριστή

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

1. Τι κάνει η επέκταση

Η επέκταση προσθέτει στο Magento checkout μέθοδο πληρωμής με ανακατεύθυνση στο Piraeus Bank e-Commerce / PayCenter. Ο πελάτης επιλέγει τη μέθοδο πληρωμής στο checkout, το Magento δημιουργεί παραγγελία, ζητά payment ticket από την τράπεζα και μεταφέρει τον πελάτη στο ασφαλές περιβάλλον πληρωμής της Τράπεζας Πειραιώς.

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

2. Ποιοι το χρησιμοποιούν

• Διαχειριστές καταστήματος: ρυθμίζουν credentials, endpoints, δόσεις, γλώσσα, νομίσματα και χώρες.
• Υπεύθυνοι παραγγελιών: ελέγχουν αν μια πληρωμή εγκρίθηκε, απέτυχε ή ακυρώθηκε.
• Ομάδα υποστήριξης: χρησιμοποιεί transaction details και logs για να απαντήσει σε πελάτες ή να ελέγξει προβλήματα.
• Πελάτες: βλέπουν τη μέθοδο πληρωμής στο checkout και, αν υπάρχουν, επιλέγουν δόσεις.

3. Πριν ξεκινήσετε

Πριν ενεργοποιηθεί η μέθοδος σε παραγωγικό κατάστημα, πρέπει να υπάρχουν τα στοιχεία που δίνει η Τράπεζα Πειραιώς:

• Acquirer ID
• Merchant ID
• Pos ID
• Username για SOAP ticket generation
• Password για SOAP authentication
• Ticket Url, αν η τράπεζα έχει δώσει διαφορετικό endpoint
• Post Url, αν η τράπεζα έχει δώσει διαφορετική σελίδα πληρωμής

Το Magento πρέπει επίσης να έχει σωστά ρυθμισμένο νόμισμα, φόρους και μεταφορικά. Το τελικό ποσό παραγγελίας χρησιμοποιείται για το payment ticket και για τους κανόνες δόσεων.

4. Πού βρίσκονται οι ρυθμίσεις

Οι βασικές ρυθμίσεις βρίσκονται στο:

Stores > Configuration > Sales > Payment Methods > Piraeus Bank Gateway

Οι συναλλαγές ελέγχονται από:

Sales > Transactions

Οι παραγγελίες και οι δόσεις ελέγχονται από:

Sales > Orders > [Order] > Payment Information

5. Βασικές ρυθμίσεις

Enabled

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

Debug

Ενεργοποιεί αναλυτική καταγραφή για τη ροή πληρωμής. Χρησιμοποιείται μόνο προσωρινά για διάγνωση. Τα logs γράφονται συνήθως στο:

var/log/piraeusbank/piraeusbank.log

Απενεργοποιήστε το σε παραγωγική χρήση όταν ολοκληρωθεί ο έλεγχος.

Title

Το όνομα που βλέπει ο πελάτης στο checkout. Για ελληνικό κατάστημα προτείνεται καθαρή ονομασία, όπως «Πληρωμή με κάρτα μέσω Τράπεζας Πειραιώς».

Acquirer ID, Merchant ID, Pos ID, Username, Password

Είναι τα στοιχεία σύνδεσης που δίνει η Τράπεζα Πειραιώς. Πρέπει να αντιγραφούν ακριβώς. Αν κάποιο είναι λάθος, η δημιουργία ticket αποτυγχάνει και ο πελάτης δεν μεταφέρεται στην τράπεζα.

New Order Status

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

Request Type

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

Installments

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

90:3;180:6

Στο παράδειγμα, για καλάθι από 90 ευρώ εμφανίζεται επιλογή έως 3 δόσεις και για καλάθι από 180 ευρώ έως 6 δόσεις. Αν το πεδίο είναι κενό, δεν εμφανίζεται επιλογή δόσεων.

Language

Η γλώσσα που ζητείται για τη σελίδα πληρωμής της τράπεζας, για παράδειγμα Ελληνικά ή Αγγλικά. Η τελική εμφάνιση εξαρτάται και από το περιβάλλον της τράπεζας.

Allowed Currencies

Περιορίζει τη μέθοδο πληρωμής σε συγκεκριμένα νομίσματα. Αν το νόμισμα του checkout δεν επιτρέπεται, η μέθοδος δεν εμφανίζεται.

Payment from Applicable Countries

Ορίζει αν η μέθοδος πληρωμής εμφανίζεται για όλες τις επιτρεπόμενες χώρες ή μόνο για συγκεκριμένες χώρες.

Instructions

Προαιρετικό κείμενο που εμφανίζεται κάτω από τη μέθοδο πληρωμής στο checkout. Χρησιμοποιήστε σύντομο ελληνικό κείμενο που εξηγεί ότι ο πελάτης θα μεταφερθεί στο ασφαλές περιβάλλον της Τράπεζας Πειραιώς.

Sort Order

Ορίζει τη σειρά εμφάνισης σε σχέση με τις υπόλοιπες μεθόδους πληρωμής.

Ticket Url και Post Url

Τα endpoints της τράπεζας. Το Ticket Url χρησιμοποιείται για τη δημιουργία payment ticket μέσω SOAP. Το Post Url είναι η σελίδα της τράπεζας όπου μεταφέρεται ο πελάτης για να πληρώσει. Αλλάξτε τα μόνο αν η τράπεζα έχει δώσει συγκεκριμένες οδηγίες.

6. Ροή πληρωμής στο checkout

1. Ο πελάτης συμπληρώνει τα στοιχεία checkout.
2. Επιλέγει την πληρωμή με Τράπεζα Πειραιώς.
3. Αν υπάρχουν δόσεις και το ποσό τις επιτρέπει, επιλέγει αριθμό δόσεων.
4. Πατάει ολοκλήρωση παραγγελίας.
5. Το Magento δημιουργεί παραγγελία σε κατάσταση αναμονής πληρωμής.
6. Η επέκταση ζητά ticket από την τράπεζα.
7. Αν το ticket δημιουργηθεί σωστά, ο πελάτης μεταφέρεται στο PayCenter.
8. Ο πελάτης ολοκληρώνει, αποτυγχάνει ή ακυρώνει την πληρωμή.
9. Η τράπεζα επιστρέφει αποτέλεσμα στο Magento.
10. Η επέκταση ενημερώνει την παραγγελία και οδηγεί τον πελάτη στη σωστή σελίδα.

7. Τι γίνεται σε επιτυχημένη πληρωμή

Όταν η τράπεζα επιστρέψει επιτυχημένο αποτέλεσμα, η επέκταση:

• ελέγχει το callback,
• ολοκληρώνει τη Magento checkout session,
• ενημερώνει την πληρωμή της παραγγελίας,
• δημιουργεί ή ενημερώνει transaction record,
• αποθηκεύει τα διαθέσιμα στοιχεία τράπεζας στα transaction details,
• οδηγεί τον πελάτη στη σελίδα επιτυχίας.

Ανάλογα με τη ρύθμιση και τη ροή της τράπεζας, η πληρωμή μπορεί να χαρακτηριστεί ως captured ή authorized.

8. Τι γίνεται σε αποτυχία ή ακύρωση

Αν η πληρωμή αποτύχει ή ο πελάτης την ακυρώσει στο περιβάλλον της τράπεζας, η επέκταση:

• ακυρώνει την παραγγελία στο Magento,
• κρατά διαθέσιμα στοιχεία επιστροφής για έλεγχο,
• επαναφέρει τα προϊόντα στο ενεργό καλάθι του πελάτη,
• οδηγεί τον πελάτη πίσω στο καλάθι με μήνυμα αποτυχίας ή ακύρωσης.

Το Magento επαναφέρει το ίδιο quote αντί να δημιουργήσει νέο καλάθι. Γι’ αυτό μπορεί να εμφανιστούν περισσότερες από μία ακυρωμένες παραγγελίες που συνδέονται με την ίδια προσπάθεια αγοράς.

9. Return Bridge και callbacks

Η τράπεζα επιστρέφει αποτελέσματα στα Magento URLs επιτυχίας, αποτυχίας και ακύρωσης. Για να μειωθούν προβλήματα με browser cookies και SameSite περιορισμούς, η επέκταση χρησιμοποιεί ενδιάμεση σελίδα επιστροφής, το Return Bridge.

Το Return Bridge παίρνει τα στοιχεία που επιστρέφει η τράπεζα και τα στέλνει ξανά στο Magento finalization endpoint με τα απαραίτητα στοιχεία, όπως order, token και outcome. Αυτό βοηθά ώστε να ολοκληρωθεί σωστά η Magento checkout session.

10. Έλεγχος συναλλαγών στο Magento Admin

Για να ελέγξετε μια συναλλαγή:

1. Μπείτε στο Magento Admin.
2. Πηγαίνετε στο Sales > Transactions.
3. Βρείτε τη συναλλαγή που αντιστοιχεί στην παραγγελία.
4. Ανοίξτε τη συναλλαγή και ελέγξτε τα transaction details.

Στα στοιχεία μπορεί να εμφανίζονται, ανάλογα με την απάντηση της τράπεζας:

• Piraeus Transaction ID
• Support Reference ID
• Approval Code
• Response Code
• Response Description
• Status
• Merchant Reference
• Trace ID
• Transaction Date Time
• Retrieval Reference
• Payment Method

Αυτά τα στοιχεία είναι χρήσιμα για συμφωνία πληρωμών, επικοινωνία με την τράπεζα και έλεγχο προβλημάτων.

11. Έλεγχος δόσεων σε παραγγελία

Αν ο πελάτης επέλεξε δόσεις:

1. Πηγαίνετε στο Sales > Orders.
2. Ανοίξτε την παραγγελία.
3. Ελέγξτε το block Payment Information.
4. Ο αριθμός δόσεων εμφανίζεται στα στοιχεία πληρωμής.

Αν δημιουργηθεί PDF τιμολόγιο, το επιλεγμένο πλήθος δόσεων μπορεί επίσης να εμφανίζεται στο PDF.

12. Συχνά προβλήματα

Ο πελάτης δεν μεταφέρεται στην τράπεζα

• Ελέγξτε αν η μέθοδος είναι ενεργή.
• Ελέγξτε Acquirer ID, Merchant ID, Pos ID, Username και Password.
• Ελέγξτε Ticket Url και Post Url.
• Ενεργοποιήστε προσωρινά Debug και δείτε το var/log/piraeusbank/piraeusbank.log.
• Ελέγξτε ότι ο server έχει ενεργό PHP SOAP extension.

Η πληρωμή επιστρέφει ως αποτυχημένη

• Ανοίξτε τη συναλλαγή στο Sales > Transactions.
• Ελέγξτε Response Code και Response Description.
• Αν χρειάζεται, στείλτε τα στοιχεία στην τράπεζα για έλεγχο.

Το καλάθι δεν επανέρχεται μετά από ακύρωση

• Ελέγξτε αν το callback ακύρωσης έφτασε στο Magento.
• Ελέγξτε αν λειτούργησε το Return Bridge.
• Ελέγξτε cookies/session ρυθμίσεις του Magento και του server.

Δεν φαίνονται transaction details

• Ελέγξτε αν η προσπάθεια πληρωμής έφτασε μέχρι την τράπεζα.
• Ελέγξτε αν η τράπεζα επέστρεψε τα σχετικά πεδία.
• Ελέγξτε τα logs για callback ή finalization errors.

13. Πριν τη live ενεργοποίηση

Πριν χρησιμοποιηθεί σε παραγωγικό περιβάλλον, κάντε πλήρη δοκιμή σε staging ή ελεγχόμενο περιβάλλον:

• επιτυχημένη πληρωμή,
• αποτυχημένη πληρωμή,
• ακύρωση από τον πελάτη,
• πληρωμή με δόσεις,
• έλεγχος transaction details,
• έλεγχος ότι το καλάθι επανέρχεται σωστά σε αποτυχία/ακύρωση,
• έλεγχος logs χωρίς μόνιμα σφάλματα,
• επιβεβαίωση με την τράπεζα ότι τα production credentials και endpoints είναι σωστά.