- Κατευθυντήριες οδηγίες ενοποίησης
- Υποστηριζόμενες δυνατότητες (Ασφάλεια)
- Ταυτοποίηση πληρωτή RuPay
- Υλοποίηση ταυτοποίησης RuPay χρησιμοποιώντας το RuPay JavaScript API
Εφαρμογή ταυτοποίησης RuPay με χρήση του RuPay JavaScript API
Αυτή η σελίδα περιγράφει τον τρόπο ενοποίησης στην πύλη για χρήση της ταυτοποίησης RuPay με το RuPay JavaScript (JS) API.
Βήμα 1: Δημιουργία και ενημέρωση περιόδου λειτουργίας
Το RuPay JS χρησιμοποιεί ταυτοποίηση βάσει περιόδου λειτουργίας. Ως πρώτο βήμα, πρέπει να δημιουργήσετε μια περίοδο λειτουργίας (session), την οποία μπορείτε στη συνέχεια να ενημερώσετε με τα πεδία αιτήματος και τις τιμές που θέλετε να αποθηκεύσετε στην περίοδο λειτουργίας.
Μπορείτε να δημιουργήσετε μια περίοδο λειτουργίας χρησιμοποιώντας την κλήση Create Session. Πρόκειται για μια κλήση API διακομιστή και αποτελεί προϋπόθεση για την ενοποίηση με το JS API. Επιστρέφει τα παρακάτω πεδία:
session.id: Ένα μοναδικό ID περιόδου λειτουργίας που πρέπει να δώσετε σε επακόλουθα αιτήματα για να γίνει αναφορά στα περιεχόμενα της περιόδου λειτουργίας.session.authenticationLimit: Το όριο που δώσατε στο αίτημα ή η προεπιλεγμένη τιμή της πύλης.session.aes256Key: Το κλειδί που μπορείτε να χρησιμοποιήσετε για την αποκρυπτογράφηση των ευαίσθητων δεδομένων που διαβιβάζονται στον ιστότοπό σας μέσω του browser ή της κινητής συσκευής του πληρωτή.session.version: Μπορείτε να χρησιμοποιήσετε αυτό το πεδίο για την υλοποίηση αισιόδοξου κλειδώματος του περιεχομένου της περιόδου λειτουργίας.session.updateStatus: Μια σύνοψη του αποτελέσματος της τελευταίας προσπάθειας τροποποίησης της περιόδου λειτουργίας.
Create Session - Αναφορά API[REST][NVP]
Μπορείτε να προσθέσετε ή να ενημερώσετε πεδία σε μια περίοδο λειτουργίας χρησιμοποιώντας την κλήση Update Session. Σας επιτρέπει να προσθέσετε δεδομένα πληρωμής και πληρωτή σε μια περίοδο λειτουργίας που μπορεί στη συνέχεια να γίνει η είσοδος για τον προσδιορισμό του κινδύνου που συσχετίζεται με έναν πληρωτή σε μια πράξη ταυτοποίησης. Τα παρακάτω πεδία απαιτούνται σε μια περίοδο λειτουργίας:
Υποχρεωτικά πεδία
- sourceOfFunds.provided.card.*: Λεπτομέρειες της κάρτας που χρησιμοποιείται για την πληρωμή.
order.amount- order.currency: Το νόμισμα της παραγγελίας.
- transaction.id: Ένα μοναδικό αναγνωριστικό για αυτή την ταυτοποίηση πληρωμής.
- order.id: Ένα μοναδικό αναγνωριστικό για αυτή την παραγγελία.
authentication.channel=PAYER_BROWSER: Το κανάλι στο οποίο εκκινείται το αίτημα ταυτοποίησης.authentication.purpose=PAYMENT_TRANSACTION: Υποδεικνύει το πλαίσιο στο οποίο ζητείται η ταυτοποίηση πληρωτή.authentication.redirectResponseUrl: Η διεύθυνση URL στην οποία θέλετε να ανακατευθύνετε τον πληρωτή μετά την ολοκλήρωση της διαδικασίας ταυτοποίησης πληρωτή.
Σημειώστε ότι δεν μπορείτε να καταργήσετε πεδία από μια περίοδο λειτουργίας, αλλά μπορείτε να αντικαταστήσετε τιμές μόνο για τα υπάρχοντα πεδία.
Βήμα 2: Προετοιμασία του API
Κάντε αναφορά στο RuPay JS API (rupay.js) από τους διακομιστές πύλης. Με αυτόν τον τρόπο, ένα αντικείμενο rupay θα τοποθετηθεί στο παράθυρο/τον καθολικό χώρο ονομάτων.
rupay.js Reference[JavaScript]
Αφού δημιουργήσετε μια περίοδο λειτουργίας (session), προετοιμάστε το API χρησιμοποιώντας τη μέθοδο configure( ). Αυτή η μέθοδος πρέπει να κληθεί κατά τη φόρτωση της σελίδας ή όταν το DOM είναι σε κατάσταση ετοιμότητας. Θα πρέπει να κληθεί μόνο μία φορά για τη φόρτωση της σελίδας. Μετά την κλήση αυτής της μεθόδου, το RuPay JS θα παράσχει τιμές διαμόρφωσης ως μεταβλητές μέλους.
Μπορείτε να προετοιμάσετε το RuPay JS API με επίκληση της μεθόδου configure(), με τα ακόλουθα υποχρεωτικά πεδία ως ορίσματα σε ένα αντικείμενο χάρτη:
merchantId: Το αναγνωριστικό σας εμπόρου στην πύλη.sessionId: Το ID περιόδου λειτουργίας που δημιουργήσατε χρησιμοποιώντας την κλήση Create Session.containerId: Το <div> id στη σύνταξη html όπου το API θα προσθέσει το κρυφό iframe.callback: Μια συνάρτηση που θα κληθεί αφού προετοιμαστεί το API.configuration: Τιμή JSON που υποστηρίζει στοιχεία δεδομένων, όπως userLanguage(optional), έκδοση REST API (wsVersion).
<html>
<head>
<script src="https://gateway-japa.americanexpress.com/static/rupay/1.0.0/rupay.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(Rupay.isConfigured());
/**
Configure method with the configuration{} parameter set and demonstrates the state change of the rupay object before and after the configure method is invoked.
*/
Rupay.configure({
merchantId: "TESTMERCHANT",
sessionId: "SESSION0002899787259G30902270H6",
containerId: "ABC",
callback: function() {
if (Rupay.isConfigured())
console.log("Done with configure");
},
configuration: {
userLanguage: "en-US",
wsVersion: 55
}
});
</script>
</head>
<body>
<div id="RupayUI"></div>
</body>
</html>
Βήμα 3: Έναρξη ταυτοποίησης
Μόλις συγκεντρωθούν όλα τα δεδομένα του πληρωτή και των πληρωμών σε μια περίοδο λειτουργίας (session), μπορείτε να ξεκινήσετε την ταυτοποίηση με επίκληση της μεθόδου initiateAuthentication(). Σας επιτρέπει να καθορίσετε αν η ταυτοποίησης πληρωτή RuPay είναι διαθέσιμη στον έμπορο για μια δεδομένη κάρτα. Αν ο τύπος κάρτας είναι RuPay, η πύλη καθορίζει την καταλληλότητα του BIN κάρτας RuPay για συναλλαγές ηλεκτρονικού εμπορίου.
Μπορείτε να ξεκινήσετε την ταυτοποίηση παρέχοντας τα ακόλουθα υποχρεωτικά πεδία στη μέθοδο initiateAuthentication():
- orderId: Το μοναδικό αναγνωριστικό για αυτή την παραγγελία.
- transactionId: Το μοναδικό αναγνωριστικό για αυτή την ταυτοποίηση πληρωμής.
- callback: Η συνάρτηση ανάκλησης.
- optionalParams: (Προαιρετικά) όρισμα με οποιαδήποτε πρόσθετα πεδία αιτήματος Initiate Authentication του REST API, όπως correlationId.
Αν είναι διαθέσιμη ταυτοποίηση RuPay του πληρωτή, τα παρακάτω πεδία επιστρέφονται στο όρισμα data της συνάρτησης ανάκλησης. Διαφορετικά, η απόκριση θα περιλαμβάνει ένα σφάλμα.
data.restApiResponse: Περιέχει ανεπεξέργαστη απόκριση από την κλήση Initiate Authentication του REST API.data.correlationId: Το τελευταίο ID συσχετισμού που χρησιμοποιήθηκε για να γίνει η κλήση Initiate Authentication του REST API. Σας επιτρέπει να αντιστοιχίσετε την απόκριση στο αίτημα.data.gatewayRecommendation
Για να καθορίσετε το επόμενο βήμα, ελέγξτε τη σύσταση της πύλης που δίνεται στο πεδίο gatewayRecommendation.
gatewayRecommendation |
Επόμενο βήμα |
|---|---|
| PROCEED | Μπορείτε να συνεχίσετε με την ταυτοποίηση του πληρωτή χρησιμοποιώντας την κλήση μεθόδου authenticatePayer( ). |
| RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | Ζητήστε από τον πληρωτή λεπτομέρειες για εναλλακτική πληρωμή (π.χ. νέα κάρτα ή άλλο τρόπο πληρωμής) και υποβάλετε ξανά το αίτημα με τις νέες λεπτομέρειες. Μην υποβάλετε ξανά το ίδιο αίτημα. |
Ο παρακάτω πίνακας εμφανίζει την απόκριση Initiate Authentication για τα διάφορα σενάρια ταυτοποίησης Rupay.
| Κατάσταση | response.gatewayRecommendation |
transaction.authenticationStatus |
response.gatewayCode |
result |
|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_AVAILABLE | AUTHENTICATION_IN_PROGRESS | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
var optionalParams = {
sourceOfFunds: {
type: "CARD"
},
order: {
walletProvider: "MASTERPASS_ONLINE"
}
};
Rupay.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 RuPay ", data);
//data.response will contain information like gatewayRecommendation, authentication version, etc.
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);
Βήμα 4: Ταυτοποίηση πληρωτή
Όταν η απόκριση Initiate Authentication έχει υποδείξει ότι είναι διαθέσιμη ταυτοποίηση (authentication.version=RUPAY) για την κάρτα RuPay, μπορείτε να κάνετε επίκληση της μεθόδου authenticatePayer(). Θα πρέπει να το επικαλεστείτε όταν ο πληρωτής κάνει κλικ στο κουμπί "Πληρωμή τώρα" στη σελίδα checkout.
Η πράξη Authenticate Payer ανταλλάσσει με ασφάλεια τις απαραίτητες πληροφορίες, συμπεριλαμβανομένου του αριθμού της κάρτας, μεταξύ της αποδέκτριας τράπεζας και του RuPay PaySecure. Το PaySecure επιστρέφει ένα μοναδικό ID συναλλαγής (tran_ID), το οποίο μπορεί να χρησιμοποιηθεί σε επακόλουθες πράξεις Authorization ή Pay.
Πρέπει να κάνετε επίκληση στη μέθοδο authenticatePayer() παρέχοντας τα ακόλουθα υποχρεωτικά πεδία:
orderId: Το ίδιο orderId όπως για τη μέθοδοinitiateAuthentication()που προηγήθηκε.transactionId: Το ίδιο transactionId όπως για τη μέθοδοinitiateAuthentication()που προηγήθηκε.callback: Η συνάρτηση ανάκλησης.optionalParams: (Προαιρετικά) ορίσματα με οποιαδήποτε πρόσθετα πεδία αιτήματος Authenticate Payer του REST API, όπωςfullScreenRedirect,billing..
Τα παρακάτω πεδία επιστρέφονται στο όρισμα data της συνάρτησης ανάκλησης:
data.restApiResponse: Περιέχει ανεπεξέργαστη απόκριση από την κλήση Authentication Payer του REST API.data.correlationId: Το τελευταίο ID συσχετισμού που χρησιμοποιήθηκε για να γίνει η κλήση Authentication Payer του REST API. Σας επιτρέπει να αντιστοιχίσετε την απόκριση στο αίτημα.data.gatewayRecommendationdata.htmlRedirectCode: Η πύλη επιστρέφει πάντα αυτό το πεδίο για εισαγωγή στη σελίδα που εμφανίζεται στον πληρωτή.
Για να καθορίσετε το επόμενο βήμα, ελέγξτε τη σύσταση της πύλης που δίνεται στο πεδίο gatewayRecommendation που επιστρέφεται στην ανάκληση.
gatewayRecommendation |
Επόμενο βήμα |
|---|---|
| Συνέχεια | Μπορείτε να συνεχίσετε στην ολοκλήρωση της διαδικασίας ταυτοποίησης (ροή challenge) ή στην ολοκλήρωση της πληρωμής (ροή frictionless). |
| DO_NOT_PROCEED_ABANDON_ORDER | Μην υποβάλετε ξανά το ίδιο αίτημα. Ο πάροχος υπηρεσιών πληρωμής, το πρόγραμμα ή ο εκδότης σας απαιτούν να εγκαταλείψετε την παραγγελία. |
| RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | Ζητήστε από τον πληρωτή λεπτομέρειες για εναλλακτική πληρωμή (π.χ. νέα κάρτα ή άλλο τρόπο πληρωμής) και υποβάλετε ξανά το αίτημα με τις νέες λεπτομέρειες. Μην υποβάλετε ξανά το ίδιο αίτημα. |
Αν η πύλη συνιστά την επιλογή PROCEED, επικολλήστε το περιεχόμενο του πεδίου απόκρισης htmlRedirectCode στη σελίδα που εμφανίζεται στον πληρωτή.
Ο παρακάτω πίνακας εμφανίζει την απόκριση authenticatePayer() για τα διάφορα σενάρια ταυτοποίησης Rupay.
| Κατάσταση | response.gatewayRecommendation |
transaction.authenticationStatus |
authentication.payerInteraction |
response.gatewayCode |
result |
|---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_PENDING | REQUIRED | PENDING | PENDING |
|
DO_NOT_PROCEED_ABANDON_ORDER | AUTHENTICATION_REJECTED | NOT_REQUIRED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
Ταυτοποίηση OTP
Η πύλη ανακατευθύνει τον browser του πληρωτή στο UI επικύρωσης OTP του εκδότη όπου θα ζητηθεί από τον πληρωτή να πληκτρολογήσει έναν έγκυρο OTP, στη συνέχεια ο πληρωτής θα ανακατευθυνθεί ξανά στον ιστότοπό σας. Τα παρακάτω πεδία επιστρέφονται στην ανάκληση όταν ο browser του πληρωτή έχει επιστρέψει στον ιστότοπό σας.
- order.id
- transaction.id
- result
- response.gatewayRecommendation
Μπορείτε να καθορίσετε το αποτέλεσμα της ταυτοποίησης χρησιμοποιώντας την τιμή που επιστρέφεται στο πεδίο response.gatewayRecommendation.
response.gatewayRecommendation |
Επόμενο βήμα |
|---|---|
| PROCEED | Μπορείτε να συνεχίσετε με την πληρωμή καθώς χορηγείται η ταυτοποίηση. Αν η έγκριση για την πληρωμή ήταν επιτυχής, προχωρήστε στη δέσμευση των κεφαλαίων και, αν είναι δυνατό, στείλτε τα αγαθά. |
| RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | Ζητήστε από τον πληρωτή λεπτομέρειες για εναλλακτική πληρωμή (π.χ. νέα κάρτα ή άλλο τρόπο πληρωμής) και υποβάλετε ξανά το αίτημα με τις νέες λεπτομέρειες. Μην υποβάλετε ξανά το ίδιο αίτημα. |
Η πύλη ενημερώνει τα πεδία απόκρισης Authentication Payer μετά την ανάκτηση των αποτελεσμάτων από την ταυτοποίηση OTP.
| Κατάσταση | response.gatewayRecommendation |
transaction.authenticationStatus |
authentication.payerInteraction |
response.gatewayCode |
result |
|---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_SUCCESSFUL | REQUIRED | APPROVED | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_FAILED | REQUIRED | DECLINED | FAILURE |
var optionalParams = {
fullScreenRedirect: true,
billing: {
address: {
city: "London",
country: "GBR"
}
}
};
Rupay.authenticatePayer("5678", "ABC", 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);
}
}, optionalParams);
Βήμα 5: Χρήση του αποτελέσματος ταυτοποίησης στην πράξη πληρωμής
Όταν το αποτέλεσμα της μεθόδου authenticatePayer() υποδεικνύει ότι μπορείτε να συνεχίσετε στην πληρωμή (gatewayRecommendation=PROCEED), μπορείτε να ξεκινήσετε μια πράξη Authorize ή Pay. Εκτός από τα τυπικά πεδία, πρέπει να παρέχετε τα ακόλουθα πεδία:
-
order.id: Δώστε το
orderIdπου παρείχατε στις μεθόδουςinitiateAuthentication()καιauthenticatePayer(). -
authentication.transactionId: Δώστε το
transactionIdπου παρείχατε στις μεθόδουςinitiateAuthentication()καιauthenticatePayer(). Δεν χρειάζεται να συμπεριλάβετε κανένα από τα πεδία στην ομάδα παραμέτρων ταυτοποίησης, καθώς η πύλη θα χρησιμοποιήσει το authentication.transactionId για να αναζητήσει τα αποτελέσματα ταυτοποίησης που αποθήκευσε όταν της ζητήσατε να εκτελέσει την ταυτοποίηση. Η πύλη διαβιβάσει τις απαιτούμενες πληροφορίες στην τράπεζα εμπόρου.
| URL | https://gateway-japa.americanexpress.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Μέθοδος HTTP | PUT |
{
"apiOperation":"PAY",
"order":{
"amount":"100",
"currency":"INR"
},
"sourceOfFunds":{
"provided":{
"card":{
"expiry":{
"month":"01",
"year":"21"
},
"number":"6074819900004939",
"securityCode":"111"
}
},
"type":"CARD"
},
"authentication": {
"transactionId":"8286737"
}
}
{
"authentication": {
"transactionId": "471707320"
},
"authorizationResponse": {
"transactionIdentifier": "500000000000000000000002347854"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTMERCHANT",
"order": {
"amount": 100.00,
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2019-07-03T09:08:28.309Z",
"currency": "INR",
"id": "802014086",
"merchantCategoryCode": "4511",
"status": "CAPTURED",
"totalAuthorizedAmount": 100.00,
"totalCapturedAmount": 100.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Success",
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "RUPAY",
"expiry": {
"month": "1",
"year": "21"
},
"fundingMethod": "DEBIT",
"issuer": "DMBB9990001",
"number": "607481xxxxxx4939",
"scheme": "RUPAY",
"storedOnFile": "NOT_STORED",
"tags": "{\"RUPAY_BIN_STATUS_FLAG\":\"ACTIVE\",\"RUPAY_BIN_MESSAGE_TYPE\":\"SMS\"}"
}
},
"type": "CARD"
},
"timeOfRecord": "2019-07-03T09:08:28.309Z",
"transaction": {
"acquirer": {
"id": "<acquirer_id>",
"merchantId": "423555234334123"
},
"amount": 100.00,
"authorizationCode": "143835",
"currency": "INR",
"frequency": "SINGLE",
"id": "108379916",
"receipt": "918409000035",
"source": "INTERNET",
"terminal": "88011019",
"type": "PAYMENT"
},
"version": "72"
}
Δοκιμή της ενοποίησής σας
Για να δοκιμάσετε την ενοποίηση, μπορείτε να χρησιμοποιήσετε το δοκιμαστικό προφίλ εμπόρου στο περιβάλλον παραγωγής.