- Κατευθυντήριες οδηγίες ενοποίησης
- Υποστηριζόμενες δυνατότητες (Τρόποι πληρωμής)
- Πληρωμές με παρουσία κατόχου κάρτας
Με παρουσία κατόχου κάρτας
Οι πληρωμές με παρουσία κατόχου κάρτας (CHP) αφορούν συναλλαγές που χρησιμοποιούν τερματικό σημείου πώλησης (POS). Το τερματικό μπορεί να διαβάσει τα δεδομένα της κάρτας ως εξής:
- βύθιση μιας κάρτας EMV
- NFC (Near Field Communication) από μια ανέπαφη κάρτα
- σάρωση κάρτας μαγνητικής ταινίας
- πληκτρολόγηση αριθμού κάρτας
Η υποστήριξη για όλα τα παραπάνω είναι διαθέσιμη από το Direct API έκδοση 40 και νεότερη.
Μια πληρωμή CHP ξεκινά από το τερματικό και αποστέλλεται στην πύλη ως συναλλαγή Verify, Authorize, Capture, Pay ή Refund. Για παράδειγμα, οι συναλλαγές που εγκρίνονται εκτός σύνδεσης από το μικροτσίπ στην κάρτα θα αποστέλλονται μόνο ως Capture, ενώ οι συναλλαγές που απαιτούν έγκριση από τον εκδότη θα χρησιμοποιούν μια ηλεκτρονική συναλλαγή Authorize και, στη συνέχεια, μια συναλλαγή Capture.
Οι συναλλαγές CHP αλληλεπιδρούν με πολλές άλλες δυνατότητες της πύλης. Μπορείτε:
- να δημιουργήσετε token για την κάρτας,
- επιστρέψετε χρήματα χρησιμοποιώντας την ίδια ενοποίηση με τις συναλλαγές ηλεκτρονικού εμπορίου σας ή μέσω του UI
- να ενοποιήσετε το ηλεκτρονικό εμπόριο και τις αναφορές CHP
Προαπαιτούμενα
Ο Your payment service provider και η τράπεζα εμπόρου πρέπει να σας επιτρέψουν να πραγματοποιείτε συναλλαγές με την παρουσία κατόχου κάρτας.
Κοινά πεδία που χρησιμοποιούνται για συναλλαγές CHP
Τα παρακάτω πεδία API είναι σχετικά με όλες τις ενοποιήσεις που έχουν παρουσία του κατόχου κάρτας μέσω της πύλης.
transaction.source=CARD_PRESENT: Αν δεν δώσετε αυτό το πεδίο, θα χρησιμοποιηθεί η προεπιλεγμένη προέλευση συναλλαγής που έχει διαμορφωθεί στον σύνδεσμο σε τράπεζα εμπόρου από τον your payment service provider. [REST][NVP]- αριθμός κάρτας: Είναι υποχρεωτικό να δώσετε τον αριθμό της κάρτας, αλλά ανάλογα με τον τρόπο ανάγνωσης της κάρτας, μέσω εισόδου κλειδιού, μαγνητικής ταινίας ή μικροτσίπ EMV, μπορείτε να τον δώσετε σε:
sourceOfFunds.provided.card.numberγια συναλλαγές με πληκτρολόγηση.sourceOfFunds.provided.card.track1ή/καιsourceOfFunds.provided.card.track2για συναλλαγές με μαγνητική ταινία, ή
τα ισοδύναμα ετικετών EMV, tag 56 και tag 57, αντιστοίχως που δίνονται στοsourceOfFunds.provided.card.emvRequestγια ανέπαφες συναλλαγές, όπου τα δεδομένα κάρτας είναι σε μορφή μαγνητικής ταινίας.- Tag 5A σε
sourceOfFunds.provided.card.emvRequestγια συναλλαγές EMV (με επαφή/ανέπαφες) όπου τα δεδομένα κάρτας είναι σε μορφή EMV. sourceOfFunds.provided.card.p2pe.payloadγια συναλλαγές P2PE (Point-to-Point Encryption) όπου τα δεδομένα κάρτας είναι σε κρυπτογραφημένη μορφή DUKPT.
- αναγνωριστικό τερματικού: Είναι υποχρεωτικό να δώσετε το αναγνωριστικό τερματικού, αλλά ανάλογα με τον τρόπο ανάγνωσης της κάρτας, μέσω εισόδου κλειδιού, μαγνητικής ταινίας ή μικροτσίπ EMV, μπορείτε να τον δώσετε σε:
posTerminal.laneγια συναλλαγές με πληκτρολόγηση και συναλλαγές με μαγνητική ταινία.- Tag 9F1C σε
sourceOfFunds.provided.card.emvRequestγια συναλλαγές EMV (με επαφή/ανέπαφες) όπου τα δεδομένα κάρτας είναι σε μορφή EMV.
Βεβαιωθείτε ότι οι τιμές για τα παρακάτω πεδία τερματικού POS έχουν οριστεί σωστά με βάση τον τρόπο με τον οποίο το τερματικό δημιούργησε τα δεδομένα της κάρτας για τη συναλλαγή. Αν είναι διαθέσιμα δεδομένα για αυτά τα πεδία, πρέπει να τα δίνετε πάντα. Η πύλη θα διαβιβάσει τα απαιτούμενα δεδομένα στην τράπεζα εμπόρου. Αν η τράπεζα εμπόρου απαιτεί ένα πεδίο και αν δεν υπάρχει, τότε η συναλλαγή θα αποτύχει.
posTerminal.addressposTerminal.attended: Αν δεν δώσετε αυτό το πεδίο, η πύλη χρησιμοποιεί από προεπιλογή την τιμήUNKNOWN_OR_UNSPECIFIEDposTerminal.authorizationMethodposTerminal.cardHolderActivated: Αν δεν δώσετε αυτό το πεδίο, η πύλη χρησιμοποιεί από προεπιλογή την τιμήNOT_CARDHOLDER_ACTIVATEDposTerminal.inputCapability: Αυτό το πεδίο είναι υποχρεωτικό για συναλλαγές EMV.posTerminal.location: Αυτό το πεδίο είναι υποχρεωτικό για συναλλαγές EMV.posTerminal.panEntryModeposTerminal.pinEntryCapabilityposTerminal.onlineReasonCode: Αυτό το πεδίο είναι υποχρεωτικό για τις εναλλακτικές συναλλαγές με μικροτσίπ (συμπεριλαμβανομένων των αντιλογισμών) για όλες τις ηλεκτρονικές συναλλαγές.posTerminal.serialNumberposTerminal.mobile.cardInputDevice: Αυτό το πεδίο ισχύει για κινητές συσκευές POS (mPOS) όπου η συσκευή λειτουργεί με πάτημα στην οθόνη ή με το κανονικό πληκτρολόγιο για εισαγωγή του PIN. Το PIN του λογισμικού πρέπει να χρησιμοποιείται μόνο για συσκευές που δεν διαθέτουν εξοπλισμό πληκτρολογίου για υποστήριξη της εισαγωγής PIN. Για τις απαιτήσεις ενοποίησης mPOS, βλ. Ενοποίηση για χρήση mPOS.order.gratuityAmount: Δώστε αυτό το πεδίο αν η πληρωμή περιλαμβάνει ένα ποσό απαλλαγής.
[REST][NVP]order.cashbackAmount: Δώστε αυτό το πεδίο αν η πληρωμή περιλαμβάνει ένα ποσό επιστροφής χρημάτων.
[REST][NVP]order.cashAdvance: Δώστε αυτό το πεδίο αν η πληρωμή περιλαμβάνει ένα ποσό προκαταβολής χρημάτων.
[REST][NVP]
Τερματικό POS - Αναφορά API [REST][NVP]
Διεκπεραίωση συναλλαγής με μαγνητική ταινία
Αν τα δεδομένα μαγνητικής ταινίας κάρτας έχουν διαβαστεί από τη μαγνητική ταινία της κάρτας,
- Δώστε τα δεδομένα μαγνητικής ταινίας 1 στο
sourceOfFunds.provided.card.track1ή τα δεδομένα μαγνητικής ταινίας 2 στα πεδίαsourceOfFunds.provided.card.track2. Αν υπάρχουν διαθέσιμα από το τερματικό και η μαγνητική ταινία 1 και η μαγνητική ταινία 2, παρέχετε και τα δύο στο αίτημα συναλλαγής. - Δώστε τα υποχρεωτικά πεδία.
- Δώστε τα προαιρετικά πεδία αν χρειάζονται.
sourceOfFunds.provided.card.track1 [REST][NVP]
sourceOfFunds.provided.card.track2 [REST][NVP]
Ακολουθεί ένα παράδειγμα μιας ηλεκτρονικής συναλλαγής Authorization που χρησιμοποιεί δεδομένα μαγνητικής ταινίας.
| URL | https://cnp.merchantlink.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Μέθοδος HTTP | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": 80,
"currency": "AUD"
},
"transaction": {
"source": "CARD_PRESENT",
"frequency": "SINGLE"
},
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5457210089020012",
"sequenceNumber": "015",
"expiry": {
"year": "39",
"month": "01"
},
"track2": ";5123456789012346=17051019681143384001?",
"track1": "%B5123456789012346^MR JOHN R SMITH ^17051019681143300001 840 ?;"
}
}
},
"posTerminal": {
"lane": "AdamLane",
"panEntryMode": "SWIPE",
"pinEntryCapability": "PIN_NOT_SUPPORTED",
"attended": "UNATTENDED",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "MAGNETIC_STRIPE",
"location": "MERCHANT_TERMINAL_OFF_PREMISES"
}
}
{
"authorizationResponse": {
"posData": "1605S0100130",
"transactionIdentifier": "AmexTidTest"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMOKE-RETAIL",
"order": {
"amount": 80,
"creationTime": "2017-05-31T07:49:46.351Z",
"currency": "AUD",
"id": "sa-e229682a-2163-47cf-b080-fb60dd148192",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 80,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"posTerminal": {
"attended": "UNATTENDED",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "MAGNETIC_STRIPE",
"lane": "AdamLane",
"location": "MERCHANT_TERMINAL_OFF_PREMISES",
"panEntryMode": "SWIPE",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"response": {
"acquirerCode": "00",
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"number": "545721xxxxxx0012",
"scheme": "MASTERCARD",
"sequenceNumber": "015",
"trackDataProvided": true
}
},
"type": "CARD"
},
"timeOfRecord": "2017-05-31T07:49:46.351Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "SYSTEST_ACQ1",
"merchantId": "12345678"
},
"amount": 80,
"authorizationCode": "000001",
"currency": "AUD",
"frequency": "SINGLE",
"id": "1",
"receipt": "1705313",
"source": "CARD_PRESENT",
"terminal": "0006",
"type": "AUTHORIZATION"
},
"version": "43"
}
Διεκπεραίωση μιας συναλλαγής με κλειδί
Αν ο αριθμός της κάρτας εισάγεται χειροκίνητα στο πληκτρολόγιο του τερματικού σας,
- Δώστε τον αριθμό κάρτας που πληκτρολογήθηκε στο πεδίο αιτήματος
sourceOfFunds.provided.card.number. - Δώστε τα υποχρεωτικά πεδία.
- Δώστε τα προαιρετικά πεδία αν χρειάζονται.
sourceOfFunds.provided.card.number[REST][NVP]
Ακολουθεί ένα παράδειγμα μιας ηλεκτρονικής συναλλαγής Authorization που χρησιμοποιεί αριθμό κάρτας που πληκτρολογήθηκε με το χέρι.
| URL | https://cnp.merchantlink.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Μέθοδος HTTP | PUT |
{
"posTerminal": {
"serialNumber": "13130PP800781435",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"lane": "S2_Lane",
"panEntryMode": "KEYED",
"pinEntryCapability": "UNKNOWN",
"attended": "ATTENDED",
"inputCapability": "KEY_ENTRY",
"location": "MERCHANT_TERMINAL_ON_PREMISES"
},
"apiOperation": "AUTHORIZE",
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5457210089020012",
"sequenceNumber": "000",
"expiry": {
"year": "39",
"month": "01"
}
}
}
},
"order": {
"amount": "100.00",
"currency": "EUR"
},
"transaction": {
"source": "CARD_PRESENT",
"frequency": "SINGLE"
}
}
{
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMOKE-RETAIL",
"order": {
"amount": 100,
"creationTime": "2017-05-31T08:59:47.194Z",
"currency": "EUR",
"id": "sa-529e784a-e11d-474d-8012-c0790531bb0f",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 100,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"posTerminal": {
"attended": "ATTENDED",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"inputCapability": "KEY_ENTRY",
"lane": "S2_Lane",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"panEntryMode": "KEYED",
"pinEntryCapability": "UNKNOWN",
"serialNumber": "13130PP800781435"
},
"response": {
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"number": "545721xxxxxx0012",
"scheme": "MASTERCARD",
"sequenceNumber": "000"
}
},
"type": "CARD"
},
"timeOfRecord": "2017-05-31T08:59:47.194Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "FOOBANK",
"merchantId": "11223344"
},
"amount": 100,
"authorizationCode": "471223",
"currency": "EUR",
"frequency": "SINGLE",
"id": "1",
"receipt": "170531475",
"source": "CARD_PRESENT",
"terminal": "0001",
"type": "AUTHORIZATION"
},
"version": "43"
}
Διεκπεραίωση μιας συναλλαγής κρυπτογράφησης P2PE (Point-to-Point)
Το P2PE είναι ένα πρότυπο που έχει καθοριστεί από το Συμβούλιο Ασφάλειας PCI. Με το P2PE, τα ευαίσθητα δεδομένα των καρτών κρυπτογραφούνται στο τερματικό αμέσως μετά την ανάγνωση των δεδομένων της κάρτας. Αυτό μεγιστοποιεί την ασφάλεια των συναλλαγών με παρουσία του κατόχου κάρτας και μειώνει τις υποχρεώσεις συμμόρφωσης PCI, καθώς δεν χρειάζεται να χειρίζεστε ευαίσθητα δεδομένα.
Για διεκπεραίωση μιας συναλλαγής P2PE:
- Δώστε τα δεδομένα DUKPT P2PE από το τερματικό στα ακόλουθα πεδία:
sourceOfFunds.provided.card.p2pe.keySerialNumber: Πρέπει να δώσετε τον αριθμό σειράς κλειδιού DUKPT που παρέχεται από το τερματικό.sourceOfFunds.provided.card.p2pe.payload: Αν δίνεται αυτό το πεδίο, τοsourceOfFunds.provided.card.numberδεν είναι υποχρεωτικό. Η πύλη θα εξαγάγει όλες τις σχετικές λεπτομέρειες της κάρτας από τα δεδομένα ωφέλιμου φορτίου που παρέχονται.posTerminal.serialNumber:sourceOfFunds.provided.card.p2pe.cardBinsourceOfFunds.provided.card.p2pe.encryptionState: Αν δεν δώσετε αυτό το πεδίο, η πύλη χρησιμοποιεί από προεπιλογή την τιμήVALIDsourceOfFunds.provided.card.p2pe.initializationVector: Αυτό το πεδίο μπορεί να παραλειφθεί αν το τερματικό δεν χρησιμοποιεί ένα διάνυσμα αρχικοποίησης για κρυπτογράφηση seed.
- Δώστε τα υποχρεωτικά πεδία.
- Δώστε τα προαιρετικά πεδία αν χρειάζονται.
P2PE - Αναφορά API [REST][NVP]
Ο παρακάτω πίνακας συνοψίζει τους περιορισμούς πεδίων για την ομάδα παραμέτρων sourceOfFunds.provided.card.p2pe.
| Αν το πεδίο | τότε η πύλη... | ||
|---|---|---|---|
sourceOfFunds.provided.card.p2pe. initializationVector |
sourceOfFunds.provided.card.p2pe. keySerialNumber |
sourceOfFunds.provided.card.p2pe. payload | |
| δίνεται | δίνεται | δεν δίνεται | απορρίπτει το αίτημα συναλλαγής. |
| δίνεται | δίνεται αλλά σε απλό κείμενο πριν ή μετά την αποκρυπτογράφηση | δίνεται | επιστρέφει ένα σφάλμα και δημιουργείται ένα αρχείο καταγραφής ασφαλείας. |
Απόκριση συναλλαγής
Το πεδίο sourceOfFunds.provided.card.encryption επιστρέφει DUKPT (από Direct API 43 και νεότερη) στην απόκριση συναλλαγής για να υποδείξει ότι τα δεδομένα της κάρτας ήταν κρυπτογραφημένα. Τα πεδία στην ομάδα παραμέτρων sourceOfFunds.provided.card.p2pe δεν επιστρέφονται στην απόκριση.
Ενοποίηση για χρήση Online PIN
Το ηλεκτρονικό PIN που εισάγεται από τον κάτοχο της κάρτας είναι κρυπτογραφημένο στην πηγή, εντός της συσκευής εισαγωγής PIN. Το Payment Gateway υποστηρίζει δεδομένα ηλεκτρονικού PIN με κρυπτογράφηση DUKPT (Derived Unique Key Per Transaction) από το Direct API έκδοση 45 και νεότερη.
- Δώστε τα δεδομένα PIN με κρυπτογράφηση DUKPT από το τερματικό στα ακόλουθα πεδία:
sourceOfFunds.provided.card.pin.payloadsourceOfFunds.provided.card.pin.keySerialNumberposTerminal.pinLengthCapabilitysourceOfFunds.provided.card.pin.encryptionState
- Δώστε τα υποχρεωτικά πεδία.
- Δώστε τα προαιρετικά πεδία αν χρειάζονται.
Ενοποίηση για χρήση mPOS
Η πύλη υποστηρίζει την αποδοχή πληρωμών σε κινητές συσκευές POS (mPOS) από την API v56 και νεότερη. Για να ενεργοποιήσετε τη λειτουργικότητα, δώστε τα ακόλουθα στη συναλλαγή Verify, Authorize, Capture, Pay ή Refund:
posTerminal.cardholderActivated=MPOS_ACCEPTANCE_DEVICE- Δώστε την τιμή της συσκευής ανάγνωσης κάρτας στο
posTerminal.mobile.cardInputDevice
BUILT_IN: Εμπορικό κινητό τηλέφωνο ή tablet με ενσωματωμένη συσκευή ανέπαφης ανάγνωσης μόνο. Σε αυτή την περίπτωση, το posTerminal.pinEntryCapability πρέπει να οριστεί σε SOFTWARE_ONLINE_PIN_ONLY, αλλιώς η πύλη απορρίπτει τη συναλλαγή.INTEGRATED_DONGLE: Αποκλειστικό κινητό τερματικό με ενσωματωμένη συσκευή ανάγνωσης κάρτας. Σε αυτή την περίπτωση, το posTerminal.pinEntryCapability πρέπει να οριστεί σε PIN_SUPPORTED or OFFLINE_PIN_ONLY, αλλιώς η πύλη απορρίπτει τη συναλλαγή.SEPARATE_DONGLE: Εμπορική συσκευή ή αποκλειστικό κινητό τερματικό με ξεχωριστή συσκευή ανάγνωσης κάρτας. Σε αυτή την περίπτωση, το posTerminal.pinEntryCapability πρέπει να οριστεί σε PIN_SUPPORTED or OFFLINE_PIN_ONLY, αλλιώς η πύλη απορρίπτει τη συναλλαγή.
- Δώστε τα υποχρεωτικά πεδία.
- Δώστε τα προαιρετικά πεδία αν χρειάζονται.
Απόκριση συναλλαγής
Η ταυτοποίηση ΡΙΝ μπορεί να αποτύχει αν ο πληρωτής εισάγει μη έγκυρο PIN, υπερβεί τις επιτρεπόμενες προσπάθειες εισαγωγής PIN ή παρακάμψει την εισαγωγή PIN όταν απαιτείται PIN για να ολοκληρωθεί η συναλλαγή.
Σε αυτά τα σενάρια όπου η ταυτοποίηση αποτυγχάνει λόγω σφάλματος ταυτοποίησης του PIN, η πύλη θα επιστρέψει συγκεκριμένους κωδικούς απόκρισης ταυτοποίησης. Μπορείτε να επαναχρησιμοποιήσετε το ίδιο ID παραγγελίας στην επακόλουθη συναλλαγή.
Παρούσα ενοποίηση δοκιμαστικού κατόχου κάρτας
Μπορείτε να δοκιμάσετε την ενοποίηση χρησιμοποιώντας κάρτες δοκιμής ειδικά για την τράπεζα εμπόρου σας.