Πληρωμή με κάρτα / IRIS¶

Με την απόφαση Α.1155/2023, όταν το τερματικό POS μιας επιχείρησης είναι «κλειδωμένο» (διασυνδεδεμένο), η χρέωση της κάρτας ή του IRIS γίνεται μόνο με Υπογραφή Παρόχου. Ο Πάροχος δίνει την υπογραφή, το POS τη χρησιμοποιεί για να χρεώσει, και μετά ολοκληρώνετε το παραστατικό.

Ποιος το χρειάζεται

Μόνο όσοι έχουν POS υποχρεωμένο σε διασύνδεση. Αυτό το ορίζει η ΑΑΔΕ ανά επιχείρηση και τερματικό, και ο Πάροχος δεν μπορεί να το γνωρίζει. Γι' αυτό υπάρχει η παράμετρος skipSignature.

Κατά την εγκύκλιο Ε.2044/2024 της ΑΑΔΕ, εκτός διασύνδεσης είναι, μεταξύ άλλων, οι πωλήσεις από απόσταση (e-shop), οι πληρωμές με payment link και όσες επιχειρήσεις δεν έχουν υποχρέωση ταμειακής (π.χ. ΠΟΛ.1002/2014, αποκλειστικά χονδρική). Εκεί στέλνετε με skipSignature=true. Για τη συγκεκριμένη περίπτωση κάθε πελάτη, την τελική απάντηση τη δίνει ο λογιστής του.

Δύο διασυνδέσεις¶

Η πληρωμή με κάρτα έχει δύο ξεχωριστές διασυνδέσεις. Ο Πάροχος δεν επικοινωνεί με το τερματικό.

Διασύνδεση	Τι κάνει	API και δοκιμαστικό
Εφαρμογή ↔ Πάροχος (Novus)	Δίνει την υπογραφή Παρόχου και, μετά τη χρέωση, διαβιβάζει το παραστατικό στην ΑΑΔΕ (MARK).	Novus: αυτή η τεκμηρίωση
Εφαρμογή ↔ POS / NSP (π.χ. Viva, Mellon, Cardlink, Worldline, Nexi, Euronet, EDPS)	Στέλνει στο τερματικό το ποσό και το token, χρεώνει την κάρτα και επιστρέφει το `transactionId`.	Ο NSP σας

Στον NSP δηλώνετε τη Novus Conceptus ως Πάροχο. Η ΑΑΔΕ έχει για εμάς δύο αναγνωριστικά, provider_id 005 και license_id 105: δοκιμάστε στο δοκιμαστικό του NSP ποιο δέχεται.

skipSignature: ο διακόπτης¶

`SendInvoices?skipSignature=`	Τι γίνεται με πληρωμή `type` 7 (κάρτα) ή 8 (IRIS)
`true` (default)	Το παραστατικό εκδίδεται αμέσως (MARK, UID, AuthCode). Δεν επιστρέφεται υπογραφή. Για POS που δεν είναι κλειδωμένο.
`false`	Το παραστατικό μένει σε αναμονή, δεν πάει ακόμη στην ΑΑΔΕ. Επιστρέφεται `providerSignature` για το POS. Για κλειδωμένο POS.

Αν το παραστατικό δεν έχει πληρωμή 7 ή 8, το skipSignature δεν έχει καμία επίδραση.

Ροή 1: έκδοση και πληρωμή μαζί (ταμείο)¶

sequenceDiagram
    autonumber
    participant APP as Ταμείο / ERP
    participant NP as Novus Provider
    participant POS as POS / NSP (τράπεζα)
    participant AADE as ΑΑΔΕ
    APP->>NP: SendInvoices?skipSignature=false<br/>paymentMethods: type 7, terminalId, posNspId
    NP-->>APP: providerSignature[].signatures[].token (+ data)
    APP->>POS: χρέωση με το token
    POS-->>APP: transactionId, τελικό paymentType (κάρτα ή IRIS)
    APP->>NP: CompletionPosInvoices [ signatureToken, transactionId, paymentAmount, paymentType ]
    NP->>AADE: διαβίβαση παραστατικού + πληρωμής
    NP-->>APP: MARK, UID, AuthCode, invoiceUrl

Βήμα 1: στείλτε το παραστατικό με skipSignature=false και, στην πληρωμή, τα terminalId και posNspId:

"paymentMethods": [ { "type": 7, "amount": 124.00, "terminalId": "TID00001", "posNspId": 1 } ]

Βήμα 2: η απάντηση έχει την υπογραφή:

"providerSignature": [
  {
    "invoiceUid": "5E1F953760F9496F5520A961DA3BE07B30ED07F8",
    "signatures": [
      {
        "token": "3045022100F0B3EAEAAC535A0C6549B42619C65895...",
        "data": "5E1F953760F9496F5520A961DA3BE07B30ED07F8;;20260924155441;10000;2400;12400;12400;TID00001",
        "createdDate": "2026-09-24T12:54:41Z",
        "expiryDate": "2026-09-25T12:54:41Z",
        "isExpired": false,
        "paymentBalance": 124,
        "issuerVatNumber": "123456789"
      }
    ]
  }
]

token: το περνάτε αυτούσιο στο API του NSP/τράπεζας. Είναι ήδη στη μορφή που θέλει ο NSP (HEX ή BASE64, βάσει του posNspId). Μην το μετατρέπετε.
data: τα δεδομένα που υπογράφηκαν. Μερικοί NSP τα ζητούν μαζί με το token.
Ισχύς: 24 ώρες. Για συναλλαγές εστίασης (specialInvoiceCategory = 12) η ισχύς είναι 2 ώρες.

Βήμα 3: χρεώστε στο POS. Ο πελάτης μπορεί να αλλάξει τρόπο (π.χ. από κάρτα σε IRIS). Κρατήστε το transactionId και τον τελικό τύπο πληρωμής.

Βήμα 4: ολοκληρώστε:

POST /api/v1/Provider/CompletionPosInvoices

[
  {
    "signatureToken": "<providerSignature[0].signatures[0].token από το SendInvoices>",
    "transactionId": "123456788555",
    "paymentAmount": 124,
    "tipAmount": 0,
    "paymentType": 7
  }
]

Πεδίο	Υποχρεωτικό	Σημείωση
`signatureToken`	ναι	Το `token` του βήματος 2.
`transactionId`	ναι	Από το POS/NSP.
`paymentAmount`	ναι	> 0 και όχι μεγαλύτερο από το `paymentBalance` της υπογραφής.
`tipAmount`	όχι	Φιλοδώρημα.
`paymentType`	όχι	Ο τελικός τύπος από το POS: 7 ή 8. Αν λείπει, θεωρείται 7.

Η απάντηση έχει την ίδια μορφή με το SendInvoices, με MARK, UID, AuthCode και invoiceUrl.

Ροή 2: πληρωμή παλιού παραστατικού (επί πιστώσει)¶

Το παραστατικό εκδόθηκε νωρίτερα (π.χ. type: 5, επί πιστώσει) και τώρα εξοφλείται με κάρτα.

POST /api/v1/Provider/AskSignatureForOldInvoice?terminalId=TID00001&posNspId=1. Το body είναι σκέτο το MARK: 400001930000001. Η απάντηση επιστρέφει token, data, paymentBalance.
Χρέωση στο POS με το token.
POST /api/v1/Provider/CompletionAskSignatureForOldInvoice?signatureToken=…&transactionId=…&paymentAmount=…&tipAmount=0&paymentType=7. Το body είναι πάλι σκέτο το MARK.

Λεπτομέρειες: Other endpoints.

Αποτυχία, ακύρωση, timeout¶

Στη Ροή 1 (έκδοση και πληρωμή μαζί), μέχρι το CompletionPosInvoices το παραστατικό μένει σε αναμονή και δεν έχει διαβιβαστεί στην ΑΑΔΕ. Αν η χρέωση στο POS δεν ολοκληρωθεί:

Τι έγινε στο POS	Τι κάνετε
Η κάρτα απορρίφθηκε ή η συναλλαγή ακυρώθηκε, και ο πελάτης ξαναδοκιμάζει με κάρτα	Νέα χρέωση με το ίδιο token, όσο ισχύει (24 ώρες, 2 ώρες στην εστίαση). Όταν πετύχει, `CompletionPosInvoices`.
Ο πελάτης πληρώνει τελικά με άλλο τρόπο (π.χ. μετρητά)	Ξαναστέλνετε το ίδιο παραστατικό, με τον ίδιο αριθμό, με τον νέο τρόπο πληρωμής. Για την υπογραφή που δεν χρησιμοποιήθηκε δεν καλείτε `CompletionPosInvoices`.
Timeout: δεν ξέρετε αν έγινε η χρέωση	Ελέγξτε πρώτα στο POS / NSP την κατάσταση της συναλλαγής. Αν χρεώθηκε, `CompletionPosInvoices` με το `transactionId`. Αν όχι, όπως στις δύο πρώτες γραμμές.

Μην καλείτε CompletionPosInvoices χωρίς επιτυχημένη χρέωση: με το completion το παραστατικό διαβιβάζεται ως εξοφλημένο με κάρτα ή IRIS.

Στη Ροή 2 το παραστατικό έχει ήδη εκδοθεί. Αν η χρέωση δεν γίνει, δεν καλείτε το completion και το παραστατικό μένει ανεξόφλητο.

Δοκιμές¶

Η Novus δεν διαθέτει POS ή simulator. Για τη χρέωση χρησιμοποιείτε το δοκιμαστικό περιβάλλον ή το test τερματικό του NSP σας.
Το δοκιμαστικό του Παρόχου επιστρέφει κανονική υπογραφή, στη μορφή που περιμένει ο NSP του posNspId (HEX ή BASE64).
Χωρίς τερματικό δοκιμάζετε όλη τη ροή από την πλευρά του Παρόχου: στο δοκιμαστικό, το CompletionPosInvoices δέχεται και δοκιμαστικό transactionId. Είναι έτοιμο στο Postman, φάκελος 4 (4.1 και 4.2).
Η πληρωμή με κάρτα / IRIS δεν πιστοποιείται. Τη δηλώνετε στην αίτηση πιστοποίησης.

Σφάλματα που θα δείτε¶

Μήνυμα	Τι σημαίνει
`If one of the payment methods requires pos then the Terminal Id (tid) field is required.`	Λείπει το `terminalId` με `skipSignature=false`.
`If one of the payment methods requires pos then the Pos Nsp Id fields is required.`	Λείπει το `posNspId`.
`The transactionId field is required.`	Completion χωρίς `transactionId`.
`One ore more of the tokens is not verified.`	Λάθος ή αλλοιωμένο token.
`One ore more of the signature token balance is not enough.`	Το `paymentAmount` ξεπερνά το υπόλοιπο της υπογραφής.
`The paymentType field only accepts values 7 or 8.`	Άλλος τύπος στο completion.

Καλό να ξέρετε¶

Κάθε γραμμή πληρωμής με υπογραφή χρεώνει 0,25 credits επιπλέον (Credits).
Το ζητούμενο paymentType στο SendInvoices δεν είναι οριστικό. Το τελικό δηλώνεται στο completion.
Αν τυπώνετε δικό σας παραστατικό, γράψτε το transactionId και την υπογραφή που χρησιμοποιήθηκε, για κάθε ποσό (κανόνες εκτύπωσης).
Σε μελλοντική έκδοση το skipSignature θα καταργηθεί και η υπογραφή θα επιστρέφεται πάντα για τύπους 7/8.

Ειδικές περιπτώσεις¶

Περίπτωση	Πώς γίνεται
Πολλά τιμολόγια, ένα χτύπημα κάρτας	Ένα 8.4 (Απόδειξη Είσπραξης POS) για το συνολικό ποσό, με τα MARK των τιμολογίων που εξοφλούνται στο `invoiceHeader.multipleConnectedMarks`. Μία υπογραφή, μία χρέωση, ένα completion.
Προκαταβολή (π.χ. κράτηση που τιμολογείται αργότερα)	Τη στιγμή της προκαταβολής εκδίδετε 8.4 με `skipSignature=false`. Όταν εκδοθεί το τελικό παραστατικό, βάζετε το MARK του 8.4 στο `multipleConnectedMarks`.
Επιστροφή χρημάτων στην κάρτα	Εκδίδετε το νόμιμο πιστωτικό (π.χ. 11.4) με πληρωμή 7 ή 8 και `skipSignature=false`, όπως στην πώληση. Με την υπογραφή, το τερματικό κάνει την επιστροφή.
Mail order, δόσεις, pre-authorization	Ίδια υπογραφή με την απλή πώληση. Οι διαφορές αφορούν μόνο την επικοινωνία της εφαρμογής σας με το τερματικό.
Κωδικός Παρόχου στον NSP	Η ΑΑΔΕ έχει για τη Novus Conceptus δύο αναγνωριστικά: `provider_id` 005 και `license_id` 105. Κάθε τράπεζα / NSP ζητά ένα από τα δύο στο δικό της πεδίο (π.χ. `aadeProviderId`). Δοκιμάστε στο δοκιμαστικό του NSP ποιο δέχεται.
Viva: ΦΠΑ 2400 στο `data`	Το πεδίο ΦΠΑ στο `data` της υπογραφής είναι σταθερά `2400`, όποιοι κι αν είναι οι συντελεστές. Δεν επηρεάζει τη χρέωση. Περνάτε `token` και `data` όπως τα παίρνετε.

Αποδείξεις POS (8.4 / 8.5)¶

Για επιχειρήσεις που εισπράττουν ή επιστρέφουν ποσά μέσω POS (π.χ. για λογαριασμό τρίτων, με thirdPartyCollection).

11.1 με πληρωμή κάρτας (για skipSignature=false)