3DS με το 3DS JavaScript API
Αυτό το θέμα περιγράφει όλα τα βήματα που απαιτούνται για την προσθήκη 3DS στην ενοποίηση του American Express PSP σας χρησιμοποιώντας το 3DS JavaScript(JS) API, συμπεριλαμβανομένου του τρόπου χρήσης του αποτελέσματος ταυτοποίησης για τη διεκπεραίωση μιας πληρωμής.
Για να δείτε παραδείγματα αιτημάτων και αποκρίσεων API που χρησιμοποιούνται στη ροή 3DS με το API JavaScript 3DS, πραγματοποιήστε λήψη της συλλογής Postman.
Για περισσότερες πληροφορίες σχετικά με ορισμένες γενικές δυνατότητες 3DS που μπορείτε να αξιοποιήσετε στην ενοποίησή σας, βλ. Συχνές ερωτήσεις. Αφού ολοκληρώσετε την ενοποίησή σας, βλ. Δοκιμή της ενοποίησης 3DS για να τη δοκιμάσετε.
Προαπαιτούμενα
Για να χρησιμοποιήσετε το 3DS με το 3DS JS API:
- Υλοποιήστε τη βασική ενοποίηση Hosted Session.
- Υλοποιήστε τυχόν επακόλουθες πράξεις πληρωμής που θέλετε να χρησιμοποιήσετε με τη δημιουργημένη περίοδο λειτουργίας (session).
- Δημιουργήστε μια ξεχωριστή περίοδο λειτουργίας (session) για να συγκεντρώσετε τις λεπτομέρειες κάρτας προτού προχωρήσετε στην περίοδο λειτουργίας (session) για ταυτοποίηση.
Βήμα 1: Δημιουργία και ενημέρωση περιόδου λειτουργίας
Το 3DS JS χρησιμοποιεί ταυτοποίηση βάσει περιόδου λειτουργίας. Για περισσότερες πληροφορίες σχετικά με την ταυτοποίηση βάσει περιόδου λειτουργίας (session), βλ. Επιλογές ταυτοποίησης. Ως πρώτο βήμα, πρέπει να δημιουργήσετε μια περίοδο λειτουργίας (session), την οποία μπορείτε στη συνέχεια να ενημερώσετε με τα πεδία αιτήματος και τις τιμές που θέλετε να αποθηκεύσετε στην περίοδο λειτουργίας.
Μπορείτε να δημιουργήσετε μια περίοδο λειτουργίας χρησιμοποιώντας το αίτημα CREATE SESSION. Αυτό είναι ένα αίτημα WS API στον διακομιστή και αποτελεί προϋπόθεση για την ενοποίηση με το JS API. Επιστρέφει τα παρακάτω πεδία:
session.id
Ένα μοναδικό ID περιόδου λειτουργίας που πρέπει να δώσετε σε επακόλουθα αιτήματα για να γίνει αναφορά στα περιεχόμενα της περιόδου λειτουργίας.session.authenticationLimit
Περιορισμός στον αριθμό των αιτημάτων συναλλαγής που μπορεί να υποβάλει o browser του πληρωτή. Μπορείτε να δώσετε μια τιμή στο αίτημα ή να χρησιμοποιήσετε την προεπιλογή της πύλης. Από προεπιλογή, η πύλη το ορίζει σε 5, αλλά μπορείτε να δώσετε μια τιμή έως και 25. Αυτό το όριο αποτρέπει κακόβουλους χρήστες να χρησιμοποιούν το αίτημα ταυτοποίησης ως πιθανή επίθεση με κάρτες και να εκτελούν επιθέσεις άρνησης υπηρεσίας (DoS) στον ιστότοπό σας υποβάλλοντας μεγάλο αριθμό (πιθανώς χρεώσιμων) συναλλαγών.Κάθε επανάληψη ταυτοποίησης που ξεκινάτε ελέγχεται έναντι του ορίου ταυτοποίησης.session.aes256Key
Το κλειδί που μπορείτε να χρησιμοποιήσετε για την αποκρυπτογράφηση των ευαίσθητων δεδομένων που διαβιβάζονται στον ιστότοπό σας μέσω του browser ή της κινητής συσκευής του πληρωτή.session.version
Έκδοση της περιόδου λειτουργίας (session). Μπορείτε να χρησιμοποιήσετε αυτό το πεδίο για την υλοποίηση αισιόδοξου κλειδώματος του περιεχομένου της περιόδου λειτουργίας.session.updateStatus
Μια σύνοψη του αποτελέσματος της τελευταίας προσπάθειας τροποποίησης της περιόδου λειτουργίας.
Αφού δημιουργήσετε την περίοδο λειτουργίας, μπορείτε να προσθέσετε ή να ενημερώσετε πεδία σε μια περίοδο λειτουργίας χρησιμοποιώντας το αίτημα UPDATE SESSION. Αυτό σας επιτρέπει να προσθέσετε δεδομένα πληρωμής και πληρωτή σε μια περίοδο λειτουργίας που μπορεί στη συνέχεια να γίνει η είσοδος για τον προσδιορισμό του κινδύνου που συσχετίζεται με έναν πληρωτή σε μια πράξη ταυτοποίησης. Ο παρακάτω πίνακας ορίζει τα πεδία που χρησιμοποιούνται συνήθως σε μια περίοδο λειτουργίας.
Πίνακας: Πεδία περιόδου λειτουργίας
| Πεδίο | Υποχρεωτικό/Προαιρετικό | Περιγραφή |
|---|---|---|
session.idή sourceOfFunds.provided.card.* ήsourceOfFunds.token
|
Υποχρεωτικό | Λεπτομέρειες της κάρτας που χρησιμοποιείται για την πληρωμή. Μπορείτε επίσης να χρησιμοποιήσετε token δικτύου και token πληρωμής συσκευής ως προέλευση κεφαλαίων στην ταυτοποίηση πληρωτή. Για περισσότερες πληροφορίες, βλ. Συχνές ερωτήσεις. |
order.amount
|
Υποχρεωτικό | Συνολικό ποσό της παραγγελίας. |
order.currency
|
Υποχρεωτικό | Νόμισμα παραγγελίας. |
transaction.id
|
Υποχρεωτικό | Μοναδικό αναγνωριστικό για αυτή την ταυτοποίηση πληρωμής. |
order.id
|
Υποχρεωτικό | Μοναδικό αναγνωριστικό για αυτήν την παραγγελία. |
authentication.channel
|
Υποχρεωτικό | Κανάλι στο οποίο εκκινείται το αίτημα ταυτοποίησης. Μπορείτε να καθορίσετε μία από τις ακόλουθες τιμές:
|
authentication.redirectResponseUrl
|
Υποχρεωτικό | Η διεύθυνση URL στην οποία θέλετε να ανακατευθύνετε τον πληρωτή μετά την ολοκλήρωση της διαδικασίας ταυτοποίησης πληρωτή. Δεν χρειάζεται να δώσετε αυτήν τη διεύθυνση URL αν είστε βέβαιοι ότι δεν θα υπάρξει αλληλεπίδραση με τον πληρωτή. |
authentication.purpose
|
Προαιρετικό | Σκοπός της ταυτοποίησης. Από προεπιλογή, αυτό το πεδίο έχει οριστεί σε PAYMENT_TRANSACTION για να υποδείξει ότι η ταυτοποίηση πρέπει να εκτελείται κατά την επεξεργασία μιας πληρωμής με κάρτα. Ωστόσο, μπορείτε να καθορίσετε διαφορετικό σκοπό για να υποδείξετε ταυτοποίηση μη πληρωμής. Αν συνάπτετε μια συμφωνία πληρωμής και δεν διεκπεραιώνετε μια πληρωμή μαζί της, δώστε το ADD_CARD ως σκοπό για την ταυτοποίηση. Βλ. Πώς μπορώ να υποβάλω αίτημα ταυτοποίησης μη πληρωμής; Οι λεπτομέρειες συμφωνίας πρέπει να παρέχονται. |
authentication.acceptVersions
|
Προαιρετικό | Εκδόσεις 3DS που αποδέχεστε για αυτήν την πληρωμή. Αν δεν καθορίσετε μια έκδοση, το 3DS2 γίνεται αποδεκτό. Η πύλη χρησιμοποιεί 3DS2 αν υποστηρίζεται από τον εκδότη και την κάρτα. Αν το 3DS2 δεν είναι διαθέσιμο, η ταυτοποίηση δεν προχωράει. |
order.merchantCategoryCode
|
Προαιρετικό | Κωδικός κατηγορίας εμπόρου. Δώστε την τιμή μόνο αν θέλετε να παρακάμψετε την προεπιλεγμένη τιμή που έχει διαμορφωθεί για τον σύνδεσμο σε τράπεζα εμπόρου. |
Δεν μπορείτε να καταργήσετε πεδία από μια περίοδο λειτουργίας. Μπορείτε να αντικαταστήσετε μόνο τιμές για υπάρχοντα πεδία.
Βήμα 2: Προετοιμασία του API
Κάντε αναφορά στο 3DS JS API (threeDS.js) από τους διακομιστές πύλης. Αυτό τοποθετεί ένα αντικείμενο ThreeDS στο παράθυρο/καθολικό χώρο ονομάτων.
Αφού δημιουργήσετε μια περίοδο λειτουργίας, προετοιμάστε το 3DS JS API χρησιμοποιώντας τη συνάρτηση configure(), με τα ακόλουθα υποχρεωτικά ορίσματα στο αντικείμενο χάρτη threedsConfig:
merchantId
Το αναγνωριστικό σας εμπόρου στην πύλη.sessionId
Αναγνωριστικό περιόδου λειτουργίας που δημιουργήσατε χρησιμοποιώντας το αίτημα CREATE SESSION.containerId
<div> ID στον κώδικα HTML όπου το API εισάγει ένα κρυφό iframe.callback
Συνάρτηση για επίκληση μόλις προετοιμαστεί το API.configuration
Τιμή JSON που υποστηρίζει στοιχεία δεδομένων όπως userLanguage (γλώσσα σελίδας πληρωμής που εμφανίζεται στον χρήστη, προαιρετική) και wsVersion (έκδοση WS API).
Η συνάρτηση configure() πρέπει να κληθεί κατά τη φόρτωση της σελίδας ή όταν το DOM είναι σε κατάσταση ετοιμότητας. Πρέπει να κληθεί μόνο μία φορά για τη φόρτωση της σελίδας. Μετά την κλήση αυτής της μεθόδου, το 3DS JS παρέχει τιμές διαμόρφωσης ως μεταβλητές μέλους.
<html>
<head>
<script src="../../../../../../../static/threeDS/1.3.0/three-ds.min.js"
data-error="errorCallback"
data-cancel="cancelCallback">
</script>
<script type="text/javascript">
//The output of this call will return 'false', since the API is not configured yet
console.log(ThreeDS.isConfigured());
/**
Configure method with the configuration{} parameter set and demonstrates the state change of the ThreeDS object before and after the configure method is invoked.
*/
ThreeDS.configure({
merchantId: {merchantId},
sessionId: {sessionId},
containerId: "3DSUI",
callback: function () {
if (ThreeDS.isConfigured())
console.log("Done with configure");
},
configuration: {
userLanguage: "en-AU", //Optional parameter
wsVersion: 81
}
});
//The output of this call will return 'true', since the API is configured
console.log(ThreeDS.isConfigured());
//The output of the following code might look like "ThreeDS JS API Version : 1.2.0"
console.log("ThreeDS JS API Version : " + ThreeDS.version);
</script>
</head>
<body>
<div id="3DSUI"></div>
</body>
</html>
Βήμα 3: Έναρξη ταυτοποίησης
Μόλις συγκεντρωθούν όλα τα δεδομένα του πληρωτή και των πληρωμών σε μια περίοδο λειτουργίας (session), μπορείτε να ξεκινήσετε την ταυτοποίηση με επίκληση της συνάρτησης initiateAuthentication(). Καλεί το αίτημα INITIATE AUTHENTICATION του API ταυτοποίησης πληρωτή και καθορίζει τις εκδόσεις ταυτοποίησης πληρωτή που σας είναι διαθέσιμες για μια δεδομένη κάρτα, με βάση τα ακόλουθα:
- Οι εκδόσεις 3DS που έχουν διαμορφωθεί στο προφίλ εμπόρου σας
- Τύπος κάρτας
- Προτιμήσεις που έχετε υποδείξει στο αίτημα
- Έκδοση 3DS στην οποία έχει εγγραφεί η κάρτα
- Κανόνες φιλτραρίσματος συναλλαγών 3DS που έχουν διαμορφωθεί από εσάς ή τον Your payment service provider (PSP)
Η συνάρτηση επιτρέπει επίσης την πραγματοποίηση δραστηριοτήτων παρασκηνίου, όπως μια κλήση 3DS2 ACS, για σκοπούς όπως συλλογή πρόσθετων δεδομένων πληρωτή προς υποστήριξη μιας επακόλουθης συνάρτησης authenticatePayer().
Για να επιτρέψετε σε μια διεργασία κλήσης ACS Method να ολοκληρωθεί προτού επιχειρήσετε τη συνάρτηση authenticatePayer(), κάντε επίκληση στη συνάρτηση initiateAuthentication() το συντομότερο δυνατό στη διαδικασία checkout και ενεργήστε αμέσως αναλόγως της απόκρισης. Η πρώτη ευκαιρία είναι συνήθως όταν ο πληρωτής ολοκληρώσει την εισαγωγή του αριθμού της κάρτας στη σελίδα checkout, για παράδειγμα συμβάν onBlur στο πεδίο εισαγωγής "Αριθμός κάρτας", ή όταν επιλέξει μια κάρτα από εκείνες που καταγράφηκαν στον λογαριασμό του, αν ο ιστότοπός σας διαθέτει δυνατότητες αποθήκευσης καρτών σε αρχείο. Αφήστε τουλάχιστον 10 δευτερόλεπτα για να ολοκληρωθεί η κλήση της μεθόδου ACS.
Μπορείτε να εκκινήσετε την ταυτοποίηση καλώντας τη συνάρτηση initiateAuthentication() με τα ακόλουθα υποχρεωτικά ορίσματα:
transactionId
Μοναδικό αναγνωριστικό για αυτή την ταυτοποίηση πληρωμής.orderId
Μοναδικό αναγνωριστικό για αυτήν την παραγγελία.callback
Συνάρτηση ανάκλησης.optionalParams (optional)
Πρόσθετα πεδία, όπως το correlationId.
Αν είναι διαθέσιμη ταυτοποίηση 3DS του πληρωτή, τα ακόλουθα πεδία επιστρέφονται στο όρισμα δεδομένων της συνάρτησης ανάκλησης. Διαφορετικά, η απόκριση περιλαμβάνει ένα σφάλμα.
data.restApiResponse
Ανεπεξέργαστη απόκριση από την κλήση Initiate Authentication του REST API.data.correlationId
Το τελευταίο ID συσχετισμού που χρησιμοποιήθηκε για να γίνει η κλήση Initiate Authentication του REST API. Σας επιτρέπει να αντιστοιχίσετε την απόκριση στο αίτημα.data.gatewayRecommendation
Σύσταση για τις επόμενες ενέργειές σας, με βάση τους κανόνες φιλτραρίσματος συναλλαγών 3DS που έχουν διαμορφωθεί από εσάς ή τον PSP σας:- PROCEED: Μπορείτε να προχωρήσετε στο Βήμα 4 για την ταυτοποίηση του πληρωτή.
- RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS: Ζητήστε από τον πληρωτή εναλλακτικές λεπτομέρειες πληρωμής, για παράδειγμα, μια νέα κάρτα ή άλλον τρόπο πληρωμής και υποβάλετε ξανά το αίτημα με τις νέες λεπτομέρειες. Μην υποβάλετε ξανά το ίδιο αίτημα.
data.authenticationVersion
Επιστρέφει 3DS2 αν διατίθεται δυνατότητα ταυτοποίησης.
var optionalParams = {
sourceOfFunds: {
type: "CARD"
},
order: {
walletProvider: "MASTERPASS_ONLINE"
}
};
ThreeDS.initiateAuthentication({orderId}, {transactionId}, function (data) {
if (data && data.error) {
var error = data.error;
//Something bad happened, the error value will match what is returned by the Authentication API
console.error("error.code : ", error.code);
console.error("error.msg : ", error.msg);
console.error("error.result : ", error.result);
console.error("error.status : ", error.status);
} else {
console.log("After Initiate 3DS ", data);
//data.response will contain information like gatewayRecommendation, authentication version, and so on.
console.log("REST API raw response ", data.restApiResponse);
console.log("Correlation Id", data.correlationId);
console.log("Gateway Recommendation", data.gatewayRecommendation);
console.log("HTML Redirect Code", data.htmlRedirectCode);
console.log("Authentication Version", data.authenticationVersion);
switch (data.gatewayRecommendation) {
case "PROCEED":
authenticatePayer();//merchant's method
break;
case "RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS":
tryOtherPayment();//Card does not support 3DS and transaction filtering rules require 3DS on this transaction: Ask the payer to select a different payment method.
break;
}
}
}, optionalParams);
{
"authentication":{
"3ds2":{
"methodCompleted":false,
"methodSupported":"SUPPORTED"
},
"redirect":{
"customized":{
"3DS":{
"methodPostData":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA0LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS80ZjNmMGQyMjM5NzQwODE2OWIwMWFiYzg2OTQyZTY5NzBmODA2M2M0MDU4ZjAzNjNlOTFlMmJiOTNkOTA0NzU3IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhYWY5YjU5ZC0yZTA0LTRjZDUtOTQzOC01OGU4MGEzNzBiNWEifQ==",
"methodUrl":"<method_url>"
}
}
},
"redirectHtml":"<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://<host_name>/acs/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA0LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS80ZjNmMGQyMjM5NzQwODE2OWIwMWFiYzg2OTQyZTY5NzBmODA2M2M0MDU4ZjAzNjNlOTFlMmJiOTNkOTA0NzU3IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhYWY5YjU5ZC0yZTA0LTRjZDUtOTQzOC01OGU4MGEzNzBiNWEifQ==\" /> </form> <script>document.getElementById(\"initiate3dsSimpleRedirectForm\").submit();</script> </div>",
"version":"3DS2"
},
"order":{
"currency":"AUD",
"status":"AUTHENTICATION_INITIATED"
},
"response":{
"gatewayCode":"AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation":"PROCEED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"number":"512345xxxxxx0008"
}
},
"type":"CARD"
},
"transaction":{
"authenticationStatus":"AUTHENTICATION_AVAILABLE"
},
"version":"72"
}
Βήμα 4: Ταυτοποίηση πληρωτή
Αν η απόκριση INITIATE AUTHENTICATION έχει δείξει ότι η ταυτοποίηση είναι διαθέσιμη (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE), μπορείτε να ταυτοποιήσετε τον πληρωτή. Επικαλέστε τη συνάρτηση authenticatePayer() όταν ο πληρωτής κάνει κλικ στο κουμπί "Πληρωμή" τώρα στη σελίδα checkout. Η συνάρτηση καλεί το αίτημα AUTHENTICATE PAYER του API ταυτοποίησης πληρωτή.
Πρέπει να κάνετε επίκληση στη συνάρτηση authenticatePayer() παρέχοντας τα ακόλουθα υποχρεωτικά ορίσματα:
orderId
Το ίδιο αναγνωριστικό παραγγελίας με αυτό που χρησιμοποιήσατε στην προηγούμενη συνάρτησηinitiateAuthentication().transactionId
Το ίδιο αναγνωριστικό συναλλαγής με αυτό που χρησιμοποιήσατε στην προηγούμενη συνάρτησηinitiateAuthentication().callback
Συνάρτηση ανάκλησης.optionalParams(Optional)
Πρόσθετα πεδία αιτήματος AUTHENTICATE PAYER, όπως χρέωση και αποστολή.
Τα παρακάτω πεδία επιστρέφονται στο όρισμα data της συνάρτησης ανάκλησης:
data.restApiResponse
Ανεπεξέργαστη απόκριση από το αίτημα AUTHENTICATE PAYER. Τα επιστρεφόμενα πεδία εξαρτώνται από τη ροή (frictionless ή challenge) και το κανάλι ταυτοποίησης που έχει οριστεί για την περίοδο λειτουργίας. Για ένα αίτημα με περίοδο λειτουργίας ταυτοποίησης, η απόκριση φιλτράρεται για την κατάργηση δεδομένων που δεν σχετίζονται με τον πληρωτή και επιστρέφονται μόνο τα πεδία που ανήκουν στη λίστα εγκεκριμένων πεδίων. Για περισσότερες πληροφορίες, βλ. Βασικές αρχές της περιόδου λειτουργίας.data.correlationId
Τελευταίο ID συσχέτισης που χρησιμοποιήθηκε για την υποβολή του αιτήματος AUTHENTICATE PAYER. Σας επιτρέπει να αντιστοιχίσετε την απόκριση στο αίτημα.data.gatewayRecommendationPROCEED:Μπορείτε να συνεχίσετε στην ολοκλήρωση της διαδικασίας ταυτοποίησης (ροή challenge) ή στην ολοκλήρωση της πληρωμής (ροή frictionless). Αν η έγκριση για την πληρωμή ήταν επιτυχής, προχωρήστε στη δέσμευση των κεφαλαίων και, αν είναι δυνατό, στείλτε τα αγαθά.DO_NOT_PROCEED_ABANDON_ORDER:Μην υποβάλετε ξανά το ίδιο αίτημα. Ο PSP, το πρόγραμμα ή ο εκδότης απαιτεί από εσάς να εγκαταλείψετε την παραγγελία.RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS:Ζητήστε από τον πληρωτή εναλλακτικές λεπτομέρειες πληρωμής (για παράδειγμα, μια νέα κάρτα ή άλλο τρόπο πληρωμής) και υποβάλετε ξανά το αίτημα με τις νέες λεπτομέρειες. Μην υποβάλετε ξανά το ίδιο αίτημα.data.htmlRedirectCode
Κωδικός ανακατεύθυνσης. Αν τοgatewayRecommendationείναι PROCEED, εισαγάγετε αυτόν τον κωδικό στη σελίδα που εμφανίζεται στον πληρωτή.
Σύσταση για τις επόμενες ενέργειές σας, με βάση τους κανόνες φιλτραρίσματος συναλλαγών 3DS που έχετε διαμορφώσει εσείς ή o your payment service provider:
Αν η πύλη σάς προτείνει PROCEED:
- Αν ο ACS έχει επιλέξει ροή frictionless για τον πληρωτή, ανακατευθύνει τον browser του πληρωτή πίσω στον ιστότοπό σας και μπορείτε να προχωρήσετε στο βήμα 5 για να υποβάλετε μια επόμενη πληρωμή στην πύλη. Η πύλη λαμβάνει τα δεδομένα ταυτοποίησης που σχετίζονται με την πληρωμή και διασφαλίζει ότι οι πληρωμές διεκπεραιώνονται μόνο αν έχουν διαβιβαστεί όλοι οι κανόνες φιλτραρίσματος συναλλαγών 3DS (που έχουν ρυθμιστεί από εσάς ή τον your payment service provider).
- Αν ο ACS έχει επιλέξει μια ροή challenge για τον πληρωτή, ανακατευθύνετε τον πληρωτή στον ACS χρησιμοποιώντας το πεδίο
htmlRedirectCodeπου δίνεται στην απόκριση. Αφού ολοκληρωθεί η επιπλέον ταυτοποίηση, ο ACS ανακατευθύνει τον πληρωτή πίσω στον ιστότοπό σας και ενεργοποιεί μια ανάκληση που περιέχει τα πεδίαorderId,transactionId,gatewayRecommendationκαιrestApiResponse. Προσδιορίστε το αποτέλεσμα της ροής challenge με βάση το πεδίοgatewayRecommendation. Ισχύουν οι ίδιοι κανόνες που περιγράφονται παραπάνω για την απόκριση στη συνάρτησηauthenticatePayer(). Αν η σύσταση είναι PROCEED, συνεχίστε στο Βήμα 5.
var optionalParams = {
fullScreenRedirect: true,
billing: {
address: {
city: "London",
country: "GBR"
}
}
};
ThreeDS.authenticatePayer({orderId}, {transactionId}, function (data) {
if (!data.error) {
//data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
console.log("REST API response ", data.restApiResponse);
console.log("HTML redirect code", data.htmlRedirectCode);
displayReceipt(data);
}
}, optionalParams);
function displayReceipt(apiResponse) {
var responseBody = {
"apiResponse": apiResponse
};
var xhr = new XMLHttpRequest();
xhr.open('PUT', '3dsreceipt', true);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onreadystatechange = function () {
if (xhr.readyState == XMLHttpRequest.DONE) {
document.documentElement.innerHTML = this.response;
}
}
xhr.send(JSON.stringify(responseBody));
}
{
"authentication":{
"3ds":{
"transactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91"
},
"3ds2":{
"3dsServerTransactionId":"8c4a911c-289a-46c2-a615-887e1cc01a6a",
"acsTransactionId":"2a8234c9-e8ac-449d-a693-97a113b491fc",
"directoryServerId":"A000000004",
"dsTransactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91",
"methodCompleted":false,
"methodSupported":"SUPPORTED",
"protocolVersion":"2.1.0",
"requestorId":"test2ID",
"requestorName":"test2Name",
"transactionStatus":"C"
},
"method":"OUT_OF_BAND",
"payerInteraction":"REQUIRED",
"redirect":{
"customized":{
"3DS":{
"acsUrl":"https://<host_name>/acs/v2/prompt",
"cReq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9"
}
},
"domainName":"<domain_name>"
},
"redirectHtml":"<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"https://<host_name>/acs/v2/prompt\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9\" /> </form> <iframe id=\"challengeFrame\" name=\"challengeFrame\" width=\"100%\" height=\"100%\" ></iframe> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"threedsChallengeRedirectForm\"); if (e) { e.submit(); e.remove(); } </script> </div>",
"version":"3DS2"
},
"correlationId":"test",
"device":{
"browser":"MOZILLA",
"ipAddress":"127.0.0.1"
},
"merchant":"TEST_3DS2-1",
"order":{
"amount":100,
"authenticationStatus":"AUTHENTICATION_PENDING",
"creationTime":"2021-04-13T02:22:59.113Z",
"currency":"AUD",
"id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"lastUpdatedTime":"2021-04-13T02:44:07.161Z",
"merchantCategoryCode":"1234",
"status":"AUTHENTICATION_INITIATED",
"totalAuthorizedAmount":0,
"totalCapturedAmount":0,
"totalRefundedAmount":0,
"valueTransfer":{
"accountType":"NOT_A_TRANSFER"
}
},
"response":{
"gatewayCode":"PENDING",
"gatewayRecommendation":"PROCEED"
},
"result":"PENDING",
"sourceOfFunds":{
"provided":{
"card":{
"expiry":{
"month":"1",
"year":"39"
},
"number":"512345xxxxxx0008",
"scheme":"MASTERCARD"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2021-04-13T02:44:07.161Z",
"timeOfRecord":"2021-04-13T02:22:59.113Z",
"transaction":{
"acquirer":{
"merchantId":"99554411"
},
"amount":100,
"authenticationStatus":"AUTHENTICATION_PENDING",
"currency":"AUD",
"id":"42090084",
"type":"AUTHENTICATION"
},
"version":"60"
}
Προηγμένες ενοποιήσεις
Το αίτημα που υποβάλλεται από τον browser του πληρωτή στον ιστότοπό σας μετά την ολοκλήρωση της μεθόδου authenticatePayer() είναι παραμετροποιημένο, ώστε να καθορίσετε το αποτέλεσμα της ταυτοποίησης. Τα μεμονωμένα πεδία ταυτοποίησης, π.χ. authentication.3ds2.transactionStatus.data, μπορεί να είναι χρήσιμα για μια προηγμένη ενοποίηση ή αν χρειάζεστε να παρέχετε δεδομένα ταυτοποίησης σε μια πληρωμή που διεκπεραιώνεται μέσω άλλης πύλης. Για περισσότερες λεπτομέρειες, βλ. Πώς μπορώ να υλοποιήσω προηγμένες ενοποιήσεις για session πληρωμής (payment session);
Βήμα 5: Χρησιμοποιήστε thn ταυτοποίηση σε μια πληρωμή
Όταν το αποτέλεσμα της συνάρτησης authenticatePayer() υποδεικνύει ότι μπορείτε να συνεχίσετε με την πληρωμή (gatewayRecommendation=PROCEED), μπορείτε να ξεκινήσετε μια πράξη WS API AUTHORIZE ή PAY. Εκτός από τα τυπικά πεδία, πρέπει να παρέχετε τα ακόλουθα πεδία:
- order.id
Χρησιμοποιήστε το ίδιοorderIdπου παρείχατε στις συναρτήσειςinitiateAuthentication()καιauthenticatePayer(). - authentication.transactionId: Χρησιμοποιήστε τον ίδιο
transactionIdπου παρείχατε στις συναρτήσειςinitiateAuthentication()καιauthenticatePayer(). Δεν χρειάζεται να συμπεριλάβετε κανένα από τα πεδία στο αντικείμενοauthentication, καθώς η πύλη χρησιμοποιεί το authentication.transactionId για να αναζητήσει τα αποτελέσματα ταυτοποίησης που αποθήκευσε όταν της ζητήσατε να πραγματοποιήσει ταυτοποίηση. Η πύλη διαβιβάζει τις απαιτούμενες πληροφορίες στην τράπεζα εμπόρου.
| Διεύθυνση URL | https://gateway-japa.americanexpress.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| Μέθοδος HTTP | PUT |
{
"apiOperation":"PAY",
"authentication":{
"transactionId":"<your_transaction_ID>"
},
"session": {
"id": "<your_session_id>"
},
"transaction":{
"reference":"<your_order_ID>"
}
}
{
"authentication":{
"3ds":{
"acsEci":"02",
"authenticationToken":"kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId":"39c25b96-7bc3-4586-bee8-056479fed3af"
},
"3ds2":{
"dsTransactionId":"39c25b96-7bc3-4586-bee8-056479fed3af",
"protocolVersion":"2.1.0",
"transactionStatus":"Y"
},
"transactionId":"249213216",
"version":"3DS2"
},
"authorizationResponse":{
"posData":"1605S0100130",
"transactionIdentifier":"TidTest"
},
"device":{
"browser":"MOZILLA",
"ipAddress":"127.0.0.1"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"TEST_3DS2-1",
"order":{
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"chargeback":{
"amount":0,
"currency":"AUD"
},
"creationTime":"2021-04-13T02:11:06.102Z",
"currency":"AUD",
"id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"lastUpdatedTime":"2021-04-13T02:11:57.049Z",
"merchantAmount":100.00,
"merchantCategoryCode":"1234",
"merchantCurrency":"AUD",
"reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"status":"CAPTURED",
"totalAuthorizedAmount":100.00,
"totalCapturedAmount":100.00,
"totalRefundedAmount":0.00
},
"response":{
"acquirerCode":"00",
"gatewayCode":"APPROVED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"card":{
"brand":"MASTERCARD",
"expiry":{
"month":"1",
"year":"39"
},
"fundingMethod":"CREDIT",
"issuer":"<issuer>",
"number":"512345xxxxxx0008",
"scheme":"Mastercard",
"storedOnFile":"NOT_STORED"
}
},
"type":"CARD"
},
"timeOfLastUpdate":"2021-04-13T02:11:57.049Z",
"timeOfRecord":"2021-04-13T02:11:56.973Z",
"transaction":{
"acquirer":{
"batch":1,
"id":"<acquirer_id>",
"merchantId":"99554411"
},
"amount":100.00,
"authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
"authorizationCode":"028941",
"currency":"AUD",
"id":"1",
"receipt":"1908266016",
"reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
"source":"INTERNET",
"stan":"496",
"terminal":"1234",
"type":"PAYMENT"
},
"version":"60"
}