Κάρτα / POS¶

Q: Τι κάνω αν η πληρωμή στο POS αποτύχει, ακυρωθεί ή πάρω timeout;

Μέχρι το CompletionPosInvoices το παραστατικό μένει σε αναμονή και δεν έχει διαβιβαστεί. Αν ο πελάτης ξαναδοκιμάσει με κάρτα, χρεώνετε ξανά με το ίδιο token, όσο ισχύει (24 ώρες, 2 ώρες στην εστίαση), και κάνετε completion όταν πετύχει. Αν πληρώσει τελικά με άλλο τρόπο, ξαναστέλνετε το ίδιο παραστατικό, με τον ίδιο αριθμό, με τον νέο τρόπο πληρωμής. Σε timeout, ελέγχετε πρώτα στο POS / NSP αν έγινε η χρέωση. Completion καλείτε μόνο μετά από επιτυχημένη χρέωση. Δείτε: Πληρωμή με κάρτα / IRIS

Q: Τι γίνεται αν στείλω ξανά το ίδιο παραστατικό με άλλο τρόπο πληρωμής, ενώ η πρώτη αποστολή έγινε με κάρτα και skipSignature=false;

Με πληρωμή κάρτας ή IRIS και skipSignature=false το παραστατικό δεν διαβιβάζεται αμέσως: μένει σε αναμονή και η απάντηση φέρνει υπογραφή Παρόχου, μέχρι να καλέσετε το CompletionPosInvoices. Αν στο μεταξύ στείλετε ξανά τον ίδιο αριθμό με άλλο τρόπο πληρωμής (π.χ. επί πιστώσει), η δεύτερη κλήση εκδίδεται κανονικά και η πρώτη παραμένει σε αναμονή. Αυτό είναι και το σωστό όταν η χρέωση με κάρτα δεν έγινε και ο πελάτης πληρώνει αλλιώς: ίδιος αριθμός, νέος τρόπος πληρωμής, χωρίς completion για την υπογραφή που δεν χρησιμοποιήθηκε. Αν όμως η κάρτα χρεώθηκε, μην ξαναστέλνετε το παραστατικό: ολοκληρώστε με το CompletionPosInvoices, όπου δηλώνεται και ο τελικός τύπος πληρωμής (7 ή 8). Δείτε: Πληρωμή με κάρτα / IRIS

Q: Ποιο posNspId βάζω για ένα τερματικό POS, και σε ποια μορφή (HEX ή BASE64) θα πάρω το token;

Το posNspId λέει σε ποιον NSP ανήκει το τερματικό και καθορίζει τη μορφή και τη σειρά των πεδίων της υπογραφής, π.χ. 2 Viva: BASE64. Για NSP που δεν είναι στη λίστα, ρωτήστε τον ποιο πρωτόκολλο (μορφή και σειρά πεδίων) απαιτεί και επιλέξτε τον αντίστοιχο κωδικό, π.χ. 98 Other (HEX) ή 99 Other (BASE64). Το token επιστρέφεται ήδη στη μορφή του NSP, οπότε το περνάτε αυτούσιο, χωρίς μετατροπή. Δείτε: Γραμμές & πληρωμές

Q: Ποια είναι η σωστή μορφή του body στις κλήσεις CompletionPosInvoices και AskSignatureForOldInvoice;

Στο CompletionPosInvoices το body είναι πίνακας (array) από αντικείμενα με signatureToken, transactionId, paymentAmount και, προαιρετικά, tipAmount και paymentType· σκέτο αντικείμενο απορρίπτεται. Στο AskSignatureForOldInvoice το body είναι σκέτο το MARK του παραστατικού ως αριθμός JSON, και τα terminalId και posNspId πηγαίνουν στο query string. Το ίδιο body (το MARK) παίρνει και το CompletionAskSignatureForOldInvoice. Αν ένα παράδειγμα διαφέρει από τη συμπεριφορά του API, ισχύει το Swagger του κάθε περιβάλλοντος. Δείτε: Υπόλοιπες κλήσεις

Q: Ποια τιμή του aadeProviderId στέλνω στον NSP για τη Novus, το 005 ή το 105;

Η ΑΑΔΕ έχει για τη Novus Conceptus δύο αναγνωριστικά: provider_id 005 και license_id 105. Κάθε τράπεζα / NSP ζητά ένα από τα δύο στο δικό του πεδίο (π.χ. aadeProviderId). Δείτε στην τεκμηρίωση του NSP ποιο περιμένει και δοκιμάστε πρώτα στο δοκιμαστικό του. Δείτε: Πληρωμή με κάρτα / IRIS

Υπογραφή Παρόχου, NSP, ειδικές περιπτώσεις.

Πώς εμπλέκεται το Provider API σε πληρωμή με κάρτα ή IRIS μέσω POS και πότε επιστρέφεται υπογραφή Παρόχου;

Για POS που είναι «κλειδωμένο» κατά την Α.1155/2023, στέλνετε το παραστατικό με SendInvoices?skipSignature=false και πληρωμή type 7 (κάρτα) ή 8 (IRIS) με terminalId και posNspId. Η απάντηση φέρνει providerSignature (token, data)· το token το περνάτε αυτούσιο στο POS/NSP και, μετά τη χρέωση, καλείτε CompletionPosInvoices με signatureToken, transactionId, paymentAmount και τον τελικό paymentType, οπότε το παραστατικό διαβιβάζεται και παίρνετε MARK. Με skipSignature=true (προεπιλογή) το παραστατικό εκδίδεται αμέσως χωρίς υπογραφή. Κάθε γραμμή πληρωμής με υπογραφή χρεώνει επιπλέον 0,25 credits.

Δείτε: Πληρωμή με κάρτα / IRIS

Ποιος κάνει τη διασύνδεση της εφαρμογής μου με το τερματικό POS της τράπεζας για πληρωμές με κάρτα;

Τη διασύνδεση με το τερματικό την κάνει η εφαρμογή σας, με το API και το δοκιμαστικό περιβάλλον που δίνει η τράπεζα ή ο πάροχος πληρωμών (NSP, π.χ. Viva, Mellon, Cardlink, Worldline, Nexi, Euronet, EDPS). Είναι ξεχωριστή διασύνδεση από αυτή με τον Πάροχο, που δίνει μόνο την υπογραφή Παρόχου. Στέλνετε SendInvoices?skipSignature=false με terminalId και posNspId, περνάτε το token στο POS, και μετά τη χρέωση ολοκληρώνετε με το CompletionPosInvoices. Η ροή είναι ίδια για κάθε NSP.

Δείτε: Πληρωμή με κάρτα / IRIS

Διαθέτει η Novus test POS ή POS simulator για δοκιμές πληρωμής με κάρτα;

Όχι. Για τη χρέωση χρησιμοποιείτε το δοκιμαστικό περιβάλλον ή το test τερματικό του NSP σας (π.χ. Viva, Mellon, Cardlink, Worldline, Nexi, Euronet, EDPS). Το δοκιμαστικό του Παρόχου επιστρέφει κανονική υπογραφή, στη μορφή που περιμένει ο NSP (HEX ή BASE64), και στο δοκιμαστικό το CompletionPosInvoices δέχεται και δοκιμαστικό transactionId. Έτσι δοκιμάζετε όλη τη ροή από την πλευρά του Παρόχου χωρίς τερματικό, με έτοιμα βήματα στο Postman (φάκελος 4).

Δείτε: Πληρωμή με κάρτα / IRIS

Τι κάνω αν η πληρωμή στο POS αποτύχει, ακυρωθεί ή πάρω timeout;

Μέχρι το CompletionPosInvoices το παραστατικό μένει σε αναμονή και δεν έχει διαβιβαστεί. Αν ο πελάτης ξαναδοκιμάσει με κάρτα, χρεώνετε ξανά με το ίδιο token, όσο ισχύει (24 ώρες, 2 ώρες στην εστίαση), και κάνετε completion όταν πετύχει. Αν πληρώσει τελικά με άλλο τρόπο, ξαναστέλνετε το ίδιο παραστατικό, με τον ίδιο αριθμό, με τον νέο τρόπο πληρωμής. Σε timeout, ελέγχετε πρώτα στο POS / NSP αν έγινε η χρέωση. Completion καλείτε μόνο μετά από επιτυχημένη χρέωση.

Δείτε: Πληρωμή με κάρτα / IRIS

Χρειάζεται ξεχωριστό σενάριο δοκιμής ή πιστοποίησης για πληρωμές IRIS (paymentType 8);

Όχι. Το IRIS ακολουθεί την ίδια ροή με την κάρτα: υπογραφή Παρόχου, χρέωση στο τερματικό, CompletionPosInvoices. Αν ο πελάτης αλλάξει τρόπο στο τερματικό (π.χ. από κάρτα σε IRIS), δηλώνετε το 8 ως τελικό paymentType στο completion. Η πληρωμή με κάρτα / IRIS δεν πιστοποιείται: τη δηλώνετε στην αίτηση πιστοποίησης.

Δείτε: Πληρωμή με κάρτα / IRIS

Τι γίνεται αν στείλω ξανά το ίδιο παραστατικό με άλλο τρόπο πληρωμής, ενώ η πρώτη αποστολή έγινε με κάρτα και skipSignature=false;

Με πληρωμή κάρτας ή IRIS και skipSignature=false το παραστατικό δεν διαβιβάζεται αμέσως: μένει σε αναμονή και η απάντηση φέρνει υπογραφή Παρόχου, μέχρι να καλέσετε το CompletionPosInvoices. Αν στο μεταξύ στείλετε ξανά τον ίδιο αριθμό με άλλο τρόπο πληρωμής (π.χ. επί πιστώσει), η δεύτερη κλήση εκδίδεται κανονικά και η πρώτη παραμένει σε αναμονή. Αυτό είναι και το σωστό όταν η χρέωση με κάρτα δεν έγινε και ο πελάτης πληρώνει αλλιώς: ίδιος αριθμός, νέος τρόπος πληρωμής, χωρίς completion για την υπογραφή που δεν χρησιμοποιήθηκε. Αν όμως η κάρτα χρεώθηκε, μην ξαναστέλνετε το παραστατικό: ολοκληρώστε με το CompletionPosInvoices, όπου δηλώνεται και ο τελικός τύπος πληρωμής (7 ή 8).

Δείτε: Πληρωμή με κάρτα / IRIS

Ποιο posNspId βάζω για ένα τερματικό POS, και σε ποια μορφή (HEX ή BASE64) θα πάρω το token;

Το posNspId λέει σε ποιον NSP ανήκει το τερματικό και καθορίζει τη μορφή και τη σειρά των πεδίων της υπογραφής, π.χ. 2 Viva: BASE64. Για NSP που δεν είναι στη λίστα, ρωτήστε τον ποιο πρωτόκολλο (μορφή και σειρά πεδίων) απαιτεί και επιλέξτε τον αντίστοιχο κωδικό, π.χ. 98 Other (HEX) ή 99 Other (BASE64). Το token επιστρέφεται ήδη στη μορφή του NSP, οπότε το περνάτε αυτούσιο, χωρίς μετατροπή.

Δείτε: Γραμμές & πληρωμές

Γιατί στο data της υπογραφής Παρόχου για τη Viva το πεδίο του ΦΠΑ είναι πάντα 2400, όποιο κι αν είναι το παραστατικό;

Το πεδίο αυτό είναι πλέον legacy. Η εσωτερική διαχείριση καλύπτει και παραστατικά με πολλούς συντελεστές, οπότε η ενημέρωση προς τον NSP και την ΑΑΔΕ γίνεται με σταθερή τιμή 24,00% (2400), ανεξάρτητα από τον πραγματικό ΦΠΑ. Η τιμή αυτή δεν επηρεάζει τη χρέωση ή την ολοκλήρωση της πληρωμής. Περνάτε το token και το data όπως τα επιστρέφει ο Πάροχος.

Δείτε: Πληρωμή με κάρτα / IRIS

Ποια είναι η σωστή μορφή του body στις κλήσεις CompletionPosInvoices και AskSignatureForOldInvoice;

Στο CompletionPosInvoices το body είναι πίνακας (array) από αντικείμενα με signatureToken, transactionId, paymentAmount και, προαιρετικά, tipAmount και paymentType· σκέτο αντικείμενο απορρίπτεται. Στο AskSignatureForOldInvoice το body είναι σκέτο το MARK του παραστατικού ως αριθμός JSON, και τα terminalId και posNspId πηγαίνουν στο query string. Το ίδιο body (το MARK) παίρνει και το CompletionAskSignatureForOldInvoice. Αν ένα παράδειγμα διαφέρει από τη συμπεριφορά του API, ισχύει το Swagger του κάθε περιβάλλοντος.

Δείτε: Υπόλοιπες κλήσεις

Ποια τιμή του aadeProviderId στέλνω στον NSP για τη Novus, το 005 ή το 105;

Η ΑΑΔΕ έχει για τη Novus Conceptus δύο αναγνωριστικά: provider_id 005 και license_id 105. Κάθε τράπεζα / NSP ζητά ένα από τα δύο στο δικό του πεδίο (π.χ. aadeProviderId). Δείτε στην τεκμηρίωση του NSP ποιο περιμένει και δοκιμάστε πρώτα στο δοκιμαστικό του.

Δείτε: Πληρωμή με κάρτα / IRIS

Σε online πληρωμή με κάρτα από e-shop (χωρίς φυσικό POS) χρειάζεται υπογραφή Παρόχου;

Συνήθως όχι. Κατά την εγκύκλιο Ε.2044/2024 της ΑΑΔΕ, οι πωλήσεις από απόσταση (e-commerce) και οι πληρωμές με payment link είναι εκτός της υποχρέωσης διασύνδεσης POS. Στέλνετε SendInvoices με skipSignature=true (προεπιλογή) και τρόπο πληρωμής type 7, και το παραστατικό εκδίδεται αμέσως. Αν η ίδια επιχείρηση έχει και φυσικό POS υποχρεωμένο σε διασύνδεση, εκεί ισχύει η ροή με υπογραφή. Για τη συγκεκριμένη περίπτωση κάθε πελάτη, επιβεβαιώστε με τον λογιστή του.

Δείτε: Πληρωμή με κάρτα / IRIS

Μπορώ να εξοφλήσω πολλά ανεξόφλητα παραστατικά ενός πελάτη με ένα μόνο χτύπημα κάρτας στο POS;

Ναι, με ένα συγκεντρωτικό παραστατικό 8.4 (Απόδειξη Είσπραξης POS) για το συνολικό ποσό. Στο 8.4 βάζετε υποχρεωτικά στο invoiceHeader.multipleConnectedMarks τα MARK των ανεξόφλητων παραστατικών που εξοφλούνται, ώστε η ΑΑΔΕ να ξέρει ποια τιμολόγια καλύπτει η είσπραξη. Το στέλνετε με skipSignature=false και πληρωμή type 7 ή 8, παίρνετε μία υπογραφή Παρόχου, χρεώνετε μία φορά στο POS και ολοκληρώνετε με CompletionPosInvoices. Για εξόφληση ενός μόνο παλιού παραστατικού υπάρχει και η ροή AskSignatureForOldInvoice.

Δείτε: Πληρωμή με κάρτα / IRIS

Πώς χρεώνω προκαταβολή με κάρτα σε «κλειδωμένο» POS, όταν το κύριο παραστατικό θα εκδοθεί αργότερα (π.χ. κράτηση που τιμολογείται στο check-out);

Τη στιγμή της προκαταβολής η εφαρμογή εκδίδει 8.4 (Απόδειξη Είσπραξης POS) για το ποσό, με skipSignature=false· παίρνει την υπογραφή Παρόχου, το POS χρεώνει και η ροή κλείνει με CompletionPosInvoices. Στο 8.4 δεν δηλώνετε συσχετιζόμενα, αφού το κύριο παραστατικό δεν έχει εκδοθεί ακόμη. Όταν εκδοθεί το τελικό τιμολόγιο ή η απόδειξη, βάζετε το MARK του 8.4 στο multipleConnectedMarks.

Δείτε: Πληρωμή με κάρτα / IRIS

Πώς κάνω επιστροφή χρημάτων (refund) σε κάρτα μέσω «κλειδωμένου» POS που απαιτεί υπογραφή Παρόχου;

Δεν υπάρχει ξεχωριστό endpoint για «υπογραφή επιστροφής». Εκδίδετε το νόμιμο πιστωτικό παραστατικό (π.χ. 11.4 ή πιστωτικό τιμολόγιο) με τρόπο πληρωμής POS (type 7 ή 8) και skipSignature=false, όπως στην αρχική πώληση· με την υπογραφή Παρόχου που παίρνετε, το τερματικό κάνει την επιστροφή στην κάρτα, και κλείνετε τη ροή με CompletionPosInvoices. Για επιστροφή που γίνεται μόνο στο POS και δεν αντιστοιχεί σε εκδοθέν παραστατικό πώλησης (π.χ. επιστροφή προκαταβολής), εκδίδετε 8.5 (Απόδειξη Επιστροφής POS) και χρησιμοποιείτε την υπογραφή του.

Δείτε: Πληρωμή με κάρτα / IRIS

Για συναλλαγές POS όπως mail order, δόσεις, preloaded ή ολοκλήρωση pre-authorization χρειάζεται διαφορετική υπογραφή Παρόχου;

Όχι. Χρησιμοποιείτε την ίδια υπογραφή που επιστρέφει το SendInvoices με skipSignature=false και την περνάτε στο τερματικό όπως στην απλή πώληση. Οι ιδιαιτερότητες κάθε τύπου συναλλαγής (mail order, δόσεις, pre-authorization κ.λπ.) αφορούν μόνο την επικοινωνία της εφαρμογής σας με το τερματικό μέσω του πρωτοκόλλου του NSP και δεν επηρεάζουν την υπογραφή του Παρόχου.

Δείτε: Πληρωμή με κάρτα / IRIS