- Κατευθυντήριες οδηγίες ενοποίησης
- Υποστηριζόμενες δυνατότητες (Τρόποι πληρωμής)
- Πληρωμές με παρουσία κατόχου κάρτας
Με παρουσία κατόχου κάρτας
Οι πληρωμές με παρουσία κατόχου κάρτας (CHP) αφορούν συναλλαγές που χρησιμοποιούν τερματικό σημείου πώλησης (POS). Το τερματικό μπορεί να διαβάσει τα δεδομένα της κάρτας ως εξής:
- βύθιση μιας κάρτας EMV
- NFC (Near Field Communication) από μια ανέπαφη κάρτα
- σάρωση κάρτας μαγνητικής ταινίας
- πληκτρολόγηση αριθμού κάρτας
Η υποστήριξη για όλα τα παραπάνω είναι διαθέσιμη από το Web-Services 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]
Διεκπεραίωση μιας συναλλαγής EMV
Αν τα δεδομένα κάρτας έχουν διαβαστεί από το μικροτσίπ της κάρτας (μόνο κάρτες EMV),
- Ζητήστε το τερματικό για αυτές τις ετικέτες EMV (ετικέτες που υποστηρίζονται από την πύλη).
- Παρέχετε τις επιστρεφόμενες ετικέτες στο πεδίο
sourceOfFunds.provided.card.emvRequestως αντικείμενο JSON στο πρωτόκολλο REST ή ως συλλογή πεδίων στο πρωτόκολλο NVP (είναι εντάξει αν το τερματικό σας δεν παρέχει όλες τις υποστηριζόμενες ετικέτες EMV).Οι τιμές των ετικετών EMV πρέπει να μορφοποιηθούν ακριβώς όπως επιστρέφονται από το τερματικό — οι δυαδικές τιμές θα αντιπροσωπεύονται σε δεκαεξαδική μορφή. - Δώστε τα υποχρεωτικά πεδία.
- Δώστε τα προαιρετικά πεδία αν χρειάζονται.
sourceOfFunds.provided.card.emvRequest [REST][NVP]
Ορισμένες από τις υποστηριζόμενες ετικέτες EMV αντιστοιχούν σε βασικές έννοιες πληρωμής, όπως τον κύριο αριθμό λογαριασμού. Αυτές οι έννοιες εμφανίζονται επίσης ως πεδία αιτήματος API, όπως π.χ. sourceOfFunds.provided.card.number. Η τεκμηρίωση αναφοράς API για αυτά τα αντίστοιχα πεδία αιτήματος API δείχνει τη σύνδεσή τους στην περιγραφή. Για παράδειγμα, η περιγραφή για sourceOfFunds.provided.card.number περιέχει το κείμενο "Το πεδίο αυτό αντιστοιχεί στην ετικέτα EMV 5Α".
Αν παρέχετε δεδομένα ως ετικέτα EMV, τότε δεν χρειάζεται να παρέχετε το ίδιο πεδίο ως πεδίο αιτήματος API. Η πύλη συμπληρώνει τα αντίστοιχα πεδία αιτήματος API με τις τιμές που παρέχονται στις ετικέτες EMV, όπου υπάρχουν, και χρησιμοποιεί αυτές τις τιμές σε όλες τις εσωτερικές διεργασίες, στα μηνύματα της τράπεζας εμπόρου και στις αποκρίσεις συναλλαγών. Για παράδειγμα, αν στείλετε το sourceOfFunds.provided.card.emvRequest.9F1C με την τιμή -Lane_03’, τότε το posTerminal.lane με την τιμή -Lane_03’ αποστέλλεται στην τράπεζα εμπόρου και επιστρέφεται στην απόκριση συναλλαγής.
Αν απαιτείται, μπορείτε να επιλέξετε να δώσετε και τις ετικέτες EMV και τα αντίστοιχα πεδία αιτήματος API στο αίτημα συναλλαγής. Βλ. Σύνθετη χρήση: Δεδομένα συναλλαγών και στις ετικέτες EMV και τα πεδία αιτημάτων API.
Ακολουθεί ένα παράδειγμα αιτήματος EMV στο REST για συναλλαγή Standalone Capture όπου η έγκριση έγινε offline στην πύλη.
| URL | https://gateway-japa.americanexpress.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Μέθοδος HTTP | PUT |
{
"apiOperation": "CAPTURE",
"transaction": {
"currency": "EUR",
"amount": "10.99",
"source": "CARD_PRESENT"
},
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5457210089020012",
"expiry": {
"month": "1",
"year": "39"
},
"emvRequest": {
"82": "0000",
"95": "0000000000",
"9F02": "000000001099",
"9A": "161021",
"5F2A": "840",
"9F1A": "840",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F34": "1E0300",
"9F36": "0002",
"9C": "00",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F37": "2A4E1690",
"9F33": "E0B8C8"
}
}
}
},
"posTerminal": {
"inputCapability": "CONTACTLESS_CHIP",
"panEntryMode": "CHIP",
"pinEntryCapability": "PIN_SUPPORTED",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"lane": "Lane_03",
"attended": "ATTENDED",
"serialNumber":"123456789",
"onlineReasonCode":"FORCED_BY_MERCHANT",
"cardPresenceCapability":"CARD_PRESENT",
"authorizationMethod":"OFFLINE",
"address":
{
"country":"IRL",
"city":"Dublin"
}
}
}
{
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMOKE-RETAIL",
"order": {
"amount": 10.99,
"creationTime": "2017-06-06T09:42:54.280Z",
"currency": "EUR",
"id": "sa-dfc1b030-4520-48ec-a7e0-889999d7e4ab",
"status": "CAPTURED",
"totalAuthorizedAmount": 10.99,
"totalCapturedAmount": 10.99,
"totalRefundedAmount": 0
},
"posTerminal": {
"address": {
"city": "Dublin",
"country": "IRL"
},
"attended": "ATTENDED",
"authorizationMethod": "OFFLINE",
"cardPresenceCapability": "CARD_PRESENT",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "Lane_03",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"onlineReasonCode": "FORCED_BY_MERCHANT",
"panEntryMode": "CHIP",
"pinEntryCapability": "PIN_SUPPORTED",
"serialNumber": "123456789"
},
"response": {
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"emvRequest": {
"82": "0000",
"95": "0000000000",
"5F2A": "840",
"9A": "161021",
"9C": "00",
"9F02": "000000001099",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "840",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F33": "E0B8C8",
"9F34": "1E0300",
"9F36": "0002",
"9F37": "2A4E1690"
},
"emvResponse": {
"4D3E": "456",
"5A2F": "123"
},
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"number": "545721xxxxxx0012",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfRecord": "2017-06-06T09:42:54.280Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "FOOBANK",
"merchantId": "11223344"
},
"amount": 10.99,
"currency": "EUR",
"frequency": "SINGLE",
"id": "1",
"receipt": "1706063974",
"source": "CARD_PRESENT",
"terminal": "0001",
"type": "CAPTURE"
},
"version": "43"
}
Ακολουθεί μια λίστα ετικετών EMV που υποστηρίζονται από την πύλη. Αν κάποιο από αυτά επιστραφεί από το τερματικό, συμπεριλάβετέ το στο πεδίο sourceOfFunds.provided.card.emvRequest.
Ετικέτα EMV |
Όνομα |
Υποχρεωτικό |
|---|---|---|
| 4F | Όνομα αναγνωριστικού εφαρμογής (AID) | - |
| 56 | Μαγνητική ταινία 1 | - |
| 57 | Ισοδύναμα δεδομένα μαγνητικής ταινίας 2 | - |
| 5A | Κύριος αριθμός λογαριασμού (PAN) εφαρμογής |
- |
| 5F24 | Ημερομηνία λήξης εφαρμογής | - |
| 5F25 | Ημερομηνία έναρξης εφαρμογής | - |
| 5F28 | Κωδικός χώρας εκδότη | - |
| 5F2A | Κωδικός νομίσματος συναλλαγής | - |
| 5F34 | Αριθμός ακολουθίας κύριου αριθμού λογαριασμού (PAN) εφαρμογής |
- |
| 82 | Προφίλ ανταλλαγής εφαρμογών (AIP) | Ναι |
| 84 | Αποκλειστικό όνομα αρχείου | - |
| 87 | Δείκτης προτεραιότητας εφαρμογής | - |
| 95 | Αποτέλεσμα επαλήθευσης τερματικού (TVR) | Ναι |
| 9A | Ημερομηνία συναλλαγής | Ναι |
| 9B | Πληροφορίες κατάστασης συναλλαγής | - |
| 9C | Τύπος συναλλαγής | Ναι |
| 9F02 | Εγκεκριμένο ποσό | Ναι |
| 9F03 | Ποσό επιστροφής χρημάτων | - |
| 9F06 | Αναγνωριστικό εφαρμογής (AID) - Τερματικό | - |
| 9F07 | Έλεγχος χρήσης εφαρμογής | - |
| 9F08 | Αριθμός έκδοσης εφαρμογής - ICC | - |
| 9F09 | Αριθμός έκδοσης εφαρμογής - Τερματικό | - |
| 9F0D | Κωδικός ενέργειας εκδότη - Προεπιλογή | - |
| 9F0E | Κωδικός ενέργειας εκδότη - Άρνηση | - |
| 9F0F | Κωδικός ενέργειας εκδότη - Online | - |
| 9F10 | Δεδομένα εφαρμογής εκδότη (IAD) | Ναι |
| 9F1A | Κωδικός χώρας τερματικού | Ναι |
| 9F1C | Αναγνωριστικό τερματικού | - |
| 9F1E | Αριθμός σειράς συσκευής διεπαφής (IFD) | - |
| 9F21 | Ώρα συναλλαγής | - |
| 9F26 | Κρυπτογράφημα εφαρμογής (AC) | Ναι |
| 9F27 | Δεδομένα πληροφοριών κρυπτογραφήματος (CID) | Ναι |
| 9F33 | Δυνατότητες τερματικού | - |
| 9F34 | Αποτελέσματα μεθόδου επαλήθευσης κατόχου κάρτας (CVM) | Ναι |
| 9F35 | Τύπος τερματικού | - |
| 9F36 | Μετρητής συναλλαγών εφαρμογής | Ναι |
| 9F37 | Απρόβλεπτος αριθμός | Ναι |
| 9F39 | Λειτουργία εισόδου σημείου εξυπηρέτησης (POS) | - |
| 9F40 | Πρόσθετες δυνατότητες τερματικού | - |
| 9F41 | Μετρητής ακολουθίας συναλλαγών | - |
| 9F49 | Λίστα αντικειμένων δεδομένων ταυτοποίησης δυναμικών δεδομένων (DDOL) | - |
| 9F53 | Κωδικός κατηγορίας συναλλαγής | - |
| 9F5A | EMV (Πυρήνας 3) : Αναγνωριστικό προγράμματος εφαρμογής (ID προγράμματος) EMV (Πυρήνας 4) : Αναγνωριστικό προϊόντος συμμετοχής |
- |
| 9F5B | EMV (Πυρήνας 3) : Αποτελέσματα δέσμης ενεργειών εκδότη EMV (Πυρήνας 2) : DSDOL EMV (Πυρήνας 4) : Αριθμός συμμετοχής προϊόντος |
- |
| 9F66 | EMV (Πυρήνας 2) : PUNATC(Μαγνητική ταινία2) EMV (Πυρήνας 3): Προσδιορισμοί συναλλαγής διεκπεραιωτή (TTQ) |
- |
| 9F6E | Δείκτης παράγοντα μορφής | - |
| 9F7C | Αποκλειστικά δεδομένα πελάτη (CED) | - |
Αν παρέχετε και τις ετικέτες EMV και τα αντίστοιχα πεδία αιτήματος API στο αίτημα συναλλαγής, η πύλη χρησιμοποιεί την τιμή που παρέχεται στο αντίστοιχο πεδίο αιτήματος API. Για παράδειγμα, αν στείλετε το sourceOfFunds.provided.card.emvRequest.9F1C με την τιμή -Lane_03’ και το posTerminal.lane με την τιμή -Lane_04’, τότε το posTerminal.lane με την τιμή -Lane_04’ αποστέλλεται στην τράπεζα εμπόρου και επιστρέφεται στην απόκριση συναλλαγής. Αυτό μπορεί να είναι χρήσιμο αν θέλετε να αντικαταστήσετε τις ετικέτες EMV και να ελέγξετε τις τιμές ανά πεδίο. Σημειώστε ότι μια τέτοια χρήση είναι σπάνια και συνεπώς πρέπει να ληφθεί υπόψη μόνο αν απαιτείται από την ενοποίηση.
Υποστηριζόμενες ετικέτες EMV και τα αντίστοιχα πεδία αιτήματος API
Αυτός ο πίνακας παραθέτει ετικέτες EMV όπου η πύλη συγκεντρώνει τα αντίστοιχα πεδία αιτήματος API με τις τιμές που παρέχονται στις ετικέτες EMV.
Ετικέτα EMV |
Όνομα ετικέτας EMV |
Αντίστοιχο πεδίο αιτήματος API |
|---|---|---|
| 56 | Μαγνητική ταινία 1 | sourceOfFunds.provided.card.track1 |
| 57 | Ισοδύναμα δεδομένα μαγνητικής ταινίας 2 | sourceOfFunds.provided.card.track2 |
| 5A | Κύριος αριθμός λογαριασμού (PAN) εφαρμογής | sourceOfFunds.provided.card.number |
| 5F24 | Ημερομηνία λήξης εφαρμογής | sourceOfFunds.provided.card.expiry.year sourceOfFunds.provided.card.expiry.month |
| 5F34 | Αριθμός ακολουθίας PAN | sourceOfFunds.provided.card.sequenceNumber |
| 9C | Προκαταβολή | order.cashAdvance |
| 9F03 | Ποσό επιστροφής χρημάτων | order.cashbackAmount |
| 9F1A | Κωδικός χώρας τερματικού | posTerminal.address.country |
| 9F1C | Αναγνωριστικό τερματικού | posTerminal.lane |
| 9F1E | Αριθμός σειράς συσκευής διεπαφής | posTerminal.serialNumber |
| 9F33 | Δυνατότητες τερματικού | posTerminal.inputCapability posTerminal.pinEntryCapability |
| 9F35 | Τύπος τερματικού | posTerminal.attended posTerminal.cardholderActivated |
Η πύλη επιστρέφει το πεδίο sourceOfFunds.provided.card.emvResponse στην απόκριση Retrieve Order και Retrieve Transaction. Αυτό το πεδίο περιέχει δεδομένα που παράγονται από τον εκδότη, τα οποία η κάρτα/συσκευή μπορεί να χρησιμοποιήσει για επαλήθευση προκειμένου να ολοκληρώσει ή να απορρίψει τη συναλλαγή. Μπορεί επίσης να περιέχει πρόσθετες ετικέτες EMV από τον εκδότη, συμπεριλαμβανομένων ετικετών που επαναλαμβάνονται από το αίτημα.
Ο παρακάτω πίνακας δείχνει μερικές ετικέτες EMV που μπορεί να επιστραφούν σε μια ηλεκτρονική απόκριση Authorization.
| Ετικέτα EMV | Όνομα |
|---|---|
| 8A | Κωδικός απόκρισης έγκρισης |
| 89 | Κωδικός έγκρισης |
| 91 | Δεδομένα ταυτοποίησης εκδότη |
| 71 | Πρότυπο 1 δέσμης ενεργειών εκδότη |
| 72 | Πρότυπο 2 δέσμης ενεργειών εκδότη |
Το πεδίο sourceOfFunds.provided.card.emvRequest που παρέχεται στο αίτημα, επαναλαμβάνεται στην απόκριση όπου εξαιρούνται οι ετικέτες EMV που έχουν αναγνωριστεί ως PCI ευαίσθητες.
Η τράπεζα εμπόρου σας μπορεί να απαιτήσει να συμπεριληφθούν πρόσθετα στοιχεία δεδομένων EMV όταν ακυρώνεται μια συναλλαγή EMV. Για παράδειγμα, μπορεί να απαιτείται η ετικέτα EMV DF01 (Αποτελέσματα δέσμης ενεργειών εκδότη). Για συγκεκριμένες απαιτήσεις, επικοινωνήστε με την τράπεζα εμπόρου.
Διεκπεραίωση συναλλαγής με μαγνητική ταινία
Αν τα δεδομένα μαγνητικής ταινίας κάρτας έχουν διαβαστεί από τη μαγνητική ταινία της κάρτας,
- Δώστε τα δεδομένα μαγνητικής ταινίας 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://gateway-japa.americanexpress.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://gateway-japa.americanexpress.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 (από Web-Services API 43 και νεότερη) στην απόκριση συναλλαγής για να υποδείξει ότι τα δεδομένα της κάρτας ήταν κρυπτογραφημένα. Τα πεδία στην ομάδα παραμέτρων sourceOfFunds.provided.card.p2pe δεν επιστρέφονται στην απόκριση.
Ενοποίηση για χρήση Online PIN
Το ηλεκτρονικό PIN που εισάγεται από τον κάτοχο της κάρτας είναι κρυπτογραφημένο στην πηγή, εντός της συσκευής εισαγωγής PIN. Το American Express PSP υποστηρίζει δεδομένα ηλεκτρονικού PIN με κρυπτογράφηση DUKPT (Derived Unique Key Per Transaction) από το Web-Services 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 παραγγελίας στην επακόλουθη συναλλαγή.
Παρούσα ενοποίηση δοκιμαστικού κατόχου κάρτας
Μπορείτε να δοκιμάσετε την ενοποίηση χρησιμοποιώντας κάρτες δοκιμής ειδικά για την τράπεζα εμπόρου σας.