- Directives d'intégration
- Fonctionnalités prises en charge (Sécurité)
- Authentification du payeur RuPay
- Implémentation de l'authentification RuPay à l'aide de l'API JavaScript RuPay
Implémentation de l'authentification RuPay à l'aide de l'API JavaScript RuPay
Cette page décrit comment l'intégration de passerelle pour utiliser l'authentification RuPay à l'aide de l'API RuPay JavaScript (JS).
Étape 1 : Créer et mettre à jour une session
RuPay JS utilise l'authentification basée sur la session. La première étape consiste à créer une session que vous pouvez mettre à jour à l'aide des champs de demande et des valeurs que vous voulez stocker dans la session.
Vous pouvez créer une session à l'aide de l'appel Create Session (Créer une session). Il s'agit d'un appel d'API côté serveur et est une condition préalable à l'intégration avec l'API JS. Les champs suivants sont retournés :
session.id: identifiant de session unique que vous devez fournir lors des demandes suivantes pour faire référence au contenu de la session.session.authenticationLimit: limite indiquée dans la demande ou valeur par défaut de la passerelle.session.aes256Key: clé que vous pouvez utiliser pour décrypter les données sensibles transmises à votre site Web via le navigateur ou l'appareil mobile du payeur.session.version: vous pouvez utiliser ce champ pour implémenter un verrouillage optimiste du contenu de la session.session.updateStatus: résumé des résultats de la dernière tentative de modification de la session.
Référence de l'API Create Session (Créer une session)[REST][NVP]
Vous pouvez ajouter ou mettre à jour des champs dans une session à l'aide de l'appel Update Session (Mettre à jour la session). Il vous permet d'ajouter des données de paiement et de payeur dans une session, qui peuvent ensuite devenir l'entrée pour déterminer le risque associé à un payeur dans une opération d'authentification. Les champs suivants sont obligatoires dans une session :
Champs obligatoires
- sourceOfFunds.provided.card.* : détails de la carte utilisée pour le paiement.
order.amount- order.currency : devise de la commande.
- transaction.id : identifiant unique de cette authentification de paiement.
- order.id : identifiant unique de cette commande.
authentication.channel=PAYER_BROWSER: canal dans lequel la demande d'authentification est initiée.authentication.purpose=PAYMENT_TRANSACTION: indique le contexte dans lequel l'authentification du payeur est demandée.authentication.redirectResponseUrl: URL vers laquelle vous souhaitez rediriger le payeur après avoir terminé le processus d'authentification du payeur.
Notez que vous ne pouvez pas supprimer des champs d'une session, mais uniquement remplacer des valeurs de champs existants.
Référence de l'API Update Session (Mettre à jour la session)[REST][NVP]
Étape 2 : Initialiser l'API
Référencez l'API RuPay JS (rupay.js) à partir des serveurs de passerelle. Cela place un objet rupay dans la fenêtre / l'espace de noms global.
Référence de rupay.js[JavaScript]
Une fois la session créée, initialisez l'API à l'aide de la méthode configure( ). Cette méthode doit être appelée pendant le chargement de la page ou lorsque le DOM est prêt. Elle ne doit être appelée qu'une seule fois pour le chargement de la page. Après avoir appelé cette méthode, RuPay JS fournit les valeurs de configuration en tant que variables membres.
Vous pouvez initialiser l'API RuPay JS en appelant la méthode configure(), avec les champs obligatoires suivants comme arguments dans un objet de mappage :
merchantId: votre identifiant de commerçant sur la passerelle.sessionId: ID de session que vous avez créé à l'aide de l'appel Create Session (Créer une session).containerId: ID <div> dans votre HTML où l'API injectera une iFrame masquée.callback: fonction qui sera appelée une fois l'API initialisée.configuration: valeur JSON prenant en charge des éléments de données tels que userLanguage (facultatif) ou la version de l'API REST (wsVersion).
<html>
<head>
<script src="https://ap-gateway.mastercard.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>
Étape 3 : Initier l'authentification
Une fois toutes les données du payeur et du paiement recueillies dans une session, vous pouvez lancer l'authentification en appelant la méthode initiateAuthentication(). Cela vous permet de déterminer si l'authentification du payeur RuPay est disponible pour le commerçant pour une carte donnée. Si le type de carte est RuPay, la passerelle détermine l'éligibilité du BIN de la carte RuPay pour les transactions de commerce électronique.
Vous pouvez lancer l'authentification en renseignant les champs obligatoires suivants dans la méthode initiateAuthentication() :
- orderId : identifiant unique de cette commande.
- transactionId : identifiant unique de cette authentification de paiement.
- callback : fonction de rappel.
- optionalParams : (facultatif) argument avec tout champ de demande d'API REST Initiate Authentication (Initier l'authentification) supplémentaire, tel que correlationId.
Si l'authentification RuPay du payeur est disponible, les champs suivants sont retournés dans l'argument data de la fonction de rappel. Sinon, la réponse comprendra une erreur.
data.restApiResponse: contient une réponse brute de l'appel de l'API REST Initiate Authentication (Initier l'authentification).data.correlationId: dernier ID de corrélation utilisé pour effectuer l'appel de l'API REST Initiate Authentication (Initier l'authentification). Il vous permet de faire correspondre la réponse à la demande.data.gatewayRecommendation
Pour déterminer l'étape suivante, vérifiez la recommandation de la passerelle fournie dans le champ gatewayRecommendation.
gatewayRecommendation |
Étape suivante |
|---|---|
| PROCEED | Vous pouvez procéder à l'authentification du payeur en utilisant la méthode d'appel authenticatePayer( ). |
| RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | Demandez au payeur d'autres détails de paiement (par exemple, une nouvelle carte ou un autre mode de paiement) et soumettez à nouveau la demande avec les nouveaux détails. Ne soumettez pas à nouveau la même demande. |
Le tableau suivant présente la réponse Initiate Authentication (Initier l'authentification) pour les différents scénarios d'authentification RuPay.
| État | 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);
Étape 4 : Authentifier le payeur
Lorsque la réponse Initiate Authentication (Initier l'authentification) a indiqué que l'authentification était disponible (authentication.version=RUPAY) pour la carte RuPay, vous pouvez appeler la méthode authenticatePayer(). Vous devez appeler cette opération lorsque le payeur clique sur le bouton « Payer maintenant » sur la page de paiement.
L'opération Authenticate Payer (Authentifier le payeur) échange en toute sécurité les informations nécessaires, y compris le numéro de carte, entre la banque acquéreuse et RuPay PaySecure. PaySecure retourne un ID de transaction unique (tran_ID), qui peut être utilisé dans les opérations Authorization (Autorisation) ou Pay (Payer) ultérieures.
Vous devez appeler la méthode authenticatePayer() en renseignant les champs obligatoires suivants :
orderId: même orderId que la méthodeinitiateAuthentication()précédente.transactionId: même transactionId que la méthodeinitiateAuthentication()précédente.callback: fonction de rappel.optionalParams: (Facultatif) arguments avec tout champ de demande de l'API REST Authenticate Payer (Authenticate Payer (Authentifier le payeur) supplémentaire tel quefullScreenRedirect,billing.
Les champs suivants sont retournés dans l'argument data de la fonction de rappel :
data.restApiResponse: contient une réponse brute de l'appel de l'API REST Authenticate Payer (Authentifier le payeur).data.correlationId: dernier ID de corrélation utilisé pour effectuer l'appel de l'API REST Authenticate Payer (Authentifier le payeur). Il vous permet de faire correspondre la réponse à la demande.data.gatewayRecommendationdata.htmlRedirectCode: la passerelle renvoie toujours ce champ pour insertion dans la page affichée au payeur.
Pour déterminer l'étape suivante, vérifiez la recommandation de la passerelle fournie dans le champ gatewayRecommendation retourné dans le rappel.
gatewayRecommendation |
Étape suivante |
|---|---|
| Poursuivre | Vous pouvez poursuivre et terminer le processus d'authentification (flux d'authentification) ou terminer le paiement (flux sans friction). |
| DO_NOT_PROCEED_ABANDON_ORDER | Ne soumettez pas la même demande à nouveau. Le prestataire de services de paiement, le système ou l'émetteur vous demande d'abandonner la commande. |
| RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | Demandez au payeur d'autres détails de paiement (par exemple, une nouvelle carte ou un autre mode de paiement) et soumettez à nouveau la demande avec les nouveaux détails. Ne soumettez pas à nouveau la même demande. |
Si la passerelle vous recommande PROCEED, collez le contenu du champ de réponse htmlRedirectCode sur la page affichée au payeur.
Le tableau suivant présente la réponse authenticatePayer() pour les différents scénarios d'authentification RuPay.
| État | 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 |
Authentification par mot de passe à usage unique
La passerelle redirige le navigateur du payeur vers l'UI de validation du mot de passe à usage unique de l'émetteur où le payeur sera invité à entrer un mot de passe à usage unique valide, après quoi le payeur sera redirigé vers votre site Web. Les champs suivants sont retournés dans le rappel, une fois que le navigateur du payeur a été redirigé sur votre site Web.
- order.id
- transaction.id
- result
- response.gatewayRecommendation
Vous pouvez déterminer le résultat de l'authentification à l'aide de la valeur retournée dans le champ response.gatewayRecommendation.
response.gatewayRecommendation |
Étape suivante |
|---|---|
| PROCEED | Vous pouvez procéder au paiement car l'authentification a été accordée. Si l'autorisation de paiement a réussi, procédez à la collecte des fonds et, le cas échéant, expédiez les marchandises. |
| RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | Demandez au payeur d'autres détails de paiement (par exemple, une nouvelle carte ou un autre mode de paiement) et soumettez à nouveau la demande avec les nouveaux détails. Ne soumettez pas à nouveau la même demande. |
La passerelle met à jour les champs de la réponse Authentication Payer (Authentification du payeur) après avoir récupéré les résultats de l'authentification par mot de passe à usage unique.
| État | 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);
Étape 5 : Utiliser les résultats de l'authentification dans une opération de paiement
Lorsque le résultat de la méthode authenticatePayer() indique que vous pouvez poursuivre le paiement (gatewayRecommendation=PROCEED), vous pouvez lancer une opération Authorize (Autoriser) ou Pay (Payer). En plus des champs standard, vous devez renseigner les champs suivants :
-
order.id : indiquez l'ID
orderIdque vous avez indiqué dans les méthodesinitiateAuthentication()etauthenticatePayer(). -
authentication.transactionId : indiquez l'ID
transactionIdque vous avez indiqué dans les méthodesinitiateAuthentication()etauthenticatePayer(). Il est inutile d'inclure des champs du groupe de paramètres d'authentification, car la passerelle utilise le champ authentication.transactionId pour rechercher les résultats de l'authentification stockés lorsque vous lui demandez d'effectuer une authentification. La passerelle transmet les informations demandées à l'acquéreur.
| URL | https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Méthode 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"
}
Test de votre intégration
Pour tester votre intégration, vous pouvez utiliser votre profil de commerçant TEST dans l'environnement de production.