3DS avec l'API d'authentification du payeur
Cette rubrique décrit toutes les étapes requises pour ajouter l'authentification 3DS à votre intégration Mastercard Gateway à l'aide de l'API d'authentification du payeur, notamment comment utiliser le résultat de l'authentification pour traiter un paiement.
Pour voir des exemples de demandes et de réponses d'API utilisées dans le flux 3DS avec l'API d'authentification du payeur, téléchargez la collection Postman.
Une fois votre intégration terminée, voir Test de votre intégration 3DS pour la tester.
- Étape 1 : Initier l'authentification
- Étape 2 : Authentifier le payeur
- Étape 3 : Utiliser les résultats de l'authentification dans une opération de paiement
Conditions préalables
Comme condition préalable à cette implémentation, vous devez avoir implémenté votre intégration de base Direct Payment.
Étape 1 : Initier l'authentification
L'opération Initiate Authentication (Initier l'authentification) permet de déterminer les versions 3DS disponibles pour une carte donnée, en fonction des éléments suivants :
- les versions 3DS configurées sur votre profil de commerçant,
- Le type de carte,
- les préférences que vous avez indiquées dans la demande,
- les résultat des demandes envoyés par la passerelle aux prestataires de services d'authentification concernés pour vérifier la disponibilité ou la prise en charge de la carte donnée,
- Les règles de filtrage des transactions 3DS de la passerelle configurées par vous ou votre your payment service provider.
La fonctionnalité 3DS de la passerelle prend en charge uniquement 3DS2.
L'opération permet également d'effectuer des activités en arrière-plan, telles qu'un appel de la méthode ACS, à des fins telles que la collecte de données supplémentaires sur le payeur en vue d'une opération Authenticate Payer (Authentifier le payer) ultérieure.
Demande Initiate Authentication (Initier l'authentification)
Vous pouvez initier l'authentification en renseignant les champs suivants dans la demande Initiate Authentication (Initier l'authentification) :
Tableau : Champs de la demande Initiate Authentication (Initier l'authentification)
| Champ | Obligatoire/Facultatif | Description |
|---|---|---|
session.id ou sourceOfFunds.provided.card.* ou sourceOfFunds.token |
Obligatoire | Détails de la carte utilisée pour le paiement. Vous pouvez également utiliser des jetons de réseau et des jetons de paiement mobile comme source de fonds dans l'authentification du payeur. Pour plus d'informations, voir Questions fréquentes. |
order.currency |
Obligatoire | Devise de la commande. |
transaction.id |
Obligatoire | Identifiant unique de cette authentification de paiement. |
order.id |
Obligatoire | Identifiant unique de cette commande. |
authentication.channel |
Obligatoire | Canal dans lequel la demande d'authentification est initiée. Vous pouvez spécifier l'un des éléments suivants :
|
authentication.purpose |
Facultatif | Objectif de l'authentification. Par défaut, ce champ est défini sur « PAYMENT_TRANSACTION » pour indiquer que l'authentification doit être effectuée lors du traitement d'un paiement par carte. Cependant, vous pouvez spécifier un motif différent pour indiquer l'authentification hors paiement. Si vous établissez une entente de paiement et ne traitez pas de paiement en même temps, indiquez ADD_CARD comme objectif d'authentification. Pour plus d'informations, voir Comment puis-je soumettre une demande d'authentification hors paiement ? Pour une liste détaillée des cas d'utilisation liés à l'authentification 3-D Secure, voir Paiements initiés par le titulaire de la carte avec 3-D Secure. |
authentication.acceptVersions |
Facultatif | Versions 3DS que vous acceptez pour ce paiement. Si vous ne spécifiez pas de version, 3DS2 est accepté. La passerelle utilise l'authentification 3DS2, si prise en charge par l'émetteur et la carte. Si l'authentification 3DS2 n'est pas disponible, l'authentification ne se poursuit pas. |
order.merchantCategoryCode |
Facultatif | Code de catégorie de commerçant. Indiquez le code de catégorie du commerçant si vous souhaitez remplacer la valeur par défaut configurée sur votre lien d'acquéreur. |
Pour permettre à tout processus d'appel de méthode ACS de se terminer avant de tenter l'opération AUTHENTICATE PAYER (Authentifier le payeur), soumettez l'opération INITIATE AUTHENTICATION (Initier l'authentification) dès que possible dans votre processus de paiement et d'agir immédiatement sur la réponse. La première occasion se présente généralement lorsque le payeur termine de saisir son numéro de carte sur la page de paiement. Par exemple, lorsque l'événement onBlur du champ de saisie du numéro de carte est déclenché, ou lorsque le payeur sélectionne une carte parmi celles enregistrées sur son compte, si votre site dispose de fonctionnalités de carte enregistrées. Attendez au moins 10 secondes pour que l'appel de la méthode ACS se termine.
Si vous soumettez la demande Authenticate Payer (Authentifier le payeur) avant que l'appel de la méthode ACS ne soit terminé, la demande Authenticate Payer (Authentifier le payeur) se poursuit mais la réponse Authenticate Payer (Authentifier le payeur) contient authentication.3ds2.methodCompleted = false. Si le serveur ACS de l'émetteur a terminé avec succès l'appel de méthode pour obtenir des renseignements supplémentaires sur le navigateur du payeur, le champ authentication.3ds2.methodCompleted de la réponse AUTHENTICATE PAYER (Authentifier le payeur) est défini avec la valeur true.
Réponse Initiate Authentication (Initier l'authentification)
La passerelle renvoie les champs clés suivants dans la réponse Initiate Authentication (Initier l'authentification) :
authentication.version: Si l'authentification 3DS est disponible pour le payeur, 3DS2 est renvoyé. Sinon,NONEest renvoyé.authentication.3ds2.methodSupported: si l'authentification 3DS2 est disponible et si le serveur ACS de l'émetteur prend en charge un appel de méthode, ce champ affiche SUPPORTED. L'appel de méthode est utilisé par le serveur ACS pour recueillir des données supplémentaires avant la demande d'authentification afin d'augmenter la probabilité qu'une authentification sans friction soit disponible. L'appel de méthode est déclenché dans une iFrame masquée, il est donc invisible pour le payeur. Il ne fournit également aucun rappel lorsqu'il se termine.transaction.authenticationStatus: consultez ce champ si vous souhaitez plus de détails sur le statut d'authentification.response.gatewayRecommendation: ce champ vous permet de déterminer l'étape suivante. Veuillez noter que cette recommandation est basée uniquement sur les règles de filtrage de transaction 3DS configurées par vous-même ou par votre your payment service provider.- DO_NOT_PROCEED : ne procédez pas à l'authentification 3DS pour cette carte, mais vous pouvez procéder au paiement sans les données 3DS ou proposer au payeur d'essayer un autre mode de paiement.
- PROCEED : vous pouvez procéder à l'authentification du payeur en utilisant l'opération Authenticate Payer (Authentifier le payeur).
- 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 ; vous devrez soumettre à nouveau la demande avec les nouveaux détails. Ne soumettez pas à nouveau la même demande. Ceci est applicable à compter de la version 70 de l'API et des versions ultérieures.
authentication.redirect.html: insérer le contenu de ce champ dans la page affichée au payeur, si authentication.3ds2.methodSupported = SUPPORTED. Pour ce faire, ajoutez le contenu texte à un élément DIV masqué et spécifiez l'identifiant du script dans le HTML DOM. Cela va créer et publier le formulaire automatiquement. Par exemple :
div.innerHtml= response.authentication.redirect.html;
eval(document.getElementById('initiate-authentication-script').text)
Si la passerelle vous recommande de ne pas poursuivre, le fait d'insérer le contenu de ce champ sur votre page Web n'exécutera aucune fonctionnalité.
| URL | https://na-gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| Méthode HTTP | PUT |
{
"authentication":{
"acceptVersions":"3DS1,3DS2",
"channel":"PAYER_BROWSER",
"purpose":"PAYMENT_TRANSACTION"
},
"correlationId":"test",
"order":{
"currency":"AUD"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"<card_number>"
}
}
},
"apiOperation":"INITIATE_AUTHENTICATION"
}
{
"authentication": {
"3ds2": {
"directoryServerId": "A999999999",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "test40Field@S^2sfds2ID",
"requestorName": "test40Field@S^2sfds2Name"
},
"acceptVersions": "3DS1,3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"customizedHtml": {
"3ds2": {
"methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kbDAzYXNwYWxsMDN2Lm1wZ3NkZXYubWFzdGVyY2FyZC5pbnQvY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS9mOGIzNjQ5ZDRiOWU3OTg4M2M0ODE4MmRjZmRkY2JjYTAxMTE3MTc0ZTkxODRiODAzM2NkMzg3NTQ4MjlhMTRlIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYTdjMTU0YS1jZTZkLTRkNjYtYTc4My02MjdmZTcyMjQ4ZTEifQ==",
"methodUrl": "<method_url>"
}
},
"html": "<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=\"<method_url>" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kbDAzYXNwYWxsMDN2Lm1wZ3NkZXYubWFzdGVyY2FyZC5pbnQvY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS9mOGIzNjQ5ZDRiOWU3OTg4M2M0ODE4MmRjZmRkY2JjYTAxMTE3MTc0ZTkxODRiODAzM2NkMzg3NTQ4MjlhMTRlIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYTdjMTU0YS1jZTZkLTRkNjYtYTc4My02MjdmZTcyMjQ4ZTEifQ==\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>"
},
"version": "3DS2"
},
"correlationId": "test",
"merchant": "TEST3DS12AUTH",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2022-06-24T06:57:32.714Z",
"currency": "USD",
"id": "TEST4",
"lastUpdatedTime": "2022-06-24T06:57:32.661Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"fundingMethod": "CREDIT",
"number": "512345xxxxxx0008",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-06-24T06:57:32.661Z",
"timeOfRecord": "2022-06-24T06:57:32.714Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "USD",
"id": "1",
"type": "AUTHENTICATION"
},
"version": "67"
}
Étape 2 : Authentifier le payeur
Si la réponse Initiate Authentication (Initier l'authentification) indique que l'authentification est disponible (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE) et que toutes les données relatives au payeur et au paiement ont été recueillies, soumettre la demande Authenticate Payer (Authentifier le payeur) lorsque le payeur clique sur le bouton Payer maintenant de la page de paiement.
Utilisez la même version de l'API pour la demande AUTHENTICATE PAYER (Authentifier le payeur) que celle utilisée dans la demande INITIATE AUTHENTICATION (Initier l'authentification).
Demande Authenticate Payer (Authentifier le payeur)
Soumettez cette opération en renseignant les champs suivants :
Champs de la demande Authenticate Payer (Authentifier le payeur)
| Champ | Obligatoire/Facultatif | Description |
|---|---|---|
session.id ou sourceOfFunds.provided.card.* ou sourceOfFunds.token |
Obligatoire | Détails de la carte utilisée pour le paiement. Utilisez les mêmes détails que dans l'opération INITIATE AUTHENTICATION (Initier l'authentification) précédente. |
order.amount |
Obligatoire | Montant total de la commande. |
transaction.id |
Obligatoire | ID de la transaction. Utilisez le même transaction.id que dans l'opération Initiate Authentication (Initier l'authentification) précédente. |
order.id |
Obligatoire | ID de commande. Même order.id que dans l'opération Initiate Authentication (Initier l'authentification) précédente. |
device.ipAddress |
Facultatif | Obligatoire si authentication.channel=PAYER_BROWSER, mais avec possibilité d'exclusion si nécessaire pour se conformer à la législation locale. Requis si vous prenez en charge les authentifications ITMX Local Switch EMVCo. Les authentifications EMV 3DS prennent en charge les adresses IPv4 et IPv6 à compter de la version 79 de l'API. IPv6 n'est utilisé que dans l'authentification EMV 3DS, et non dans les opérations ultérieures Authorize (Autoriser), Pay (Payer), etc. |
sourceOfFunds.provided.card.nameOnCard |
Facultatif | Nom sur la carte. Requis si vous prenez en charge les authentifications ITMX Local Switch EMVCo. |
sourceOfFunds.provided.card.number |
Facultatif | Numéro de carte. Requis si vous prenez en charge les authentifications ITMX Local Switch EMVCo. |
sourceOfFunds.provided.card.expiry |
Facultatif | Détails de l'expiration de la carte. Requis si vous prenez en charge les authentifications ITMX Local Switch EMVCo. |
authentication.redirectResponseUrl |
Obligatoire | URL vers laquelle vous souhaitez rediriger le payeur après avoir terminé le processus d'authentification du payeur. Vous n'avez pas besoin de fournir cette URL si vous êtes certain qu'il n'y a aucune interaction avec le payeur. |
device.browser |
Facultatif | En-tête User-Agent du navigateur du payeur. Obligatoire si authentication.channel = PAYER_BROWSER. |
Objet device.browserDetails |
Facultatif | Détails du navigateur. Obligatoire si authentication.channel = PAYER_BROWSER. |
Objet billing.address object |
Facultatif | Adresse de facturation du payeur. Il est fortement recommandé de l'inclure dans votre demande chaque fois qu'il est disponible. |
Objet shipping.address |
Facultatif | Adresse d'expédition du payeur. Il est fortement recommandé de l'inclure dans votre demande chaque fois qu'il est disponible. |
Objet customer |
Facultatif | Détails du payeur. Il est fortement recommandé de l'inclure dans votre demande chaque fois qu'il est disponible. |
Réponse Authenticate Payer (Authentifier le payeur)
Les champs renvoyés dans la réponse AUTHENTICATE PAYER (Authentifier le payeur) dépendent des éléments suivants :
- Flux sans friction ou flux d'authentification.
- Comment la demande d'authentification est initiée (authentication.channel).
- Mécanisme d'authentification soit pour la demande, session, certificat ou mot de passe.
Pour une opération authentifiée par session, la réponse est filtrée pour supprimer les données qui ne sont pas liées au payeur et seuls les champs sur liste blanche sont renvoyés. Pour plus d'informations, voir Principes de base des sessions. Pour les champs renvoyés pour une demande authentifiée par certificat/mot de passe, voir Champs de réponse pour une demande authentifiée par mot de passe/certificat.
La passerelle renvoie les champs clés suivants dans la réponse AUTHENTICATE PAYER (Authentifier le payeur) :
transaction.authenticationStatus: Détails sur le statut d'authentification.response.gatewayRecommendation: Recommandation pour savoir si vous devez procéder ou non à une transaction financière, sur la base des règles de filtrage des transactions 3DS configurées par vous ou votre prestataire de services de paiement :- DO_NOT_PROCEED : ne pas poursuivre pas avec cette carte car l'authentification a été refusée ou n'est pas disponible. Toutefois, vous pouvez procéder au paiement sans les données 3DS ou proposer au payeur d'essayer un autre mode de paiement.
- PROCEED : Vous pouvez terminer le processus d'authentification, également connu sous le nom de flux d'authentification, ou terminer le paiement, également connu sous le nom de 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. Cette recommandation est applicable à partir de la version 70 de l'API et versions ultérieures.
- 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 ; vous devrez soumettre à nouveau la demande avec les nouveaux détails. Ne soumettez pas à nouveau la même demande. Cette recommandation est applicable à partir de la version 70 de l'API et versions ultérieures.
authentication.redirect.html: Insérez le contenu de ce champ sur la page affichée au payeur. Pour ce faire, ajoutez le contenu texte à un élément DIV et spécifiez l'identifiant du script dans le HTML DOM. Cela va créer et publier le formulaire automatiquement. Par exemple :
div.innerHtml= response.authentication.redirect.html; eval(document.getElementById(‘authenticate-payer-script’).text)
Si la passerelle vous recommande de ne pas poursuivre, l'insertion du contenu de ce champ sur votre page Web ne déclenche aucune fonction.
La passerelle vous recommande de poursuivre :
- Si le serveur ACS a sélectionné un flux sans friction pour le payeur, il redirige le navigateur du payeur vers votre site Web, et vous pouvez passer à l'étape 3 pour soumettre un paiement ultérieur à la passerelle. La passerelle obtient les données d'authentification relatives au paiement et veille à ce que les paiements ne soient traités que si toutes les règles de filtrage des transactions 3DS, configurées par vous ou votre prestataire de services de paiement, ont été respectées.
- Si le serveur ACS a sélectionné un flux d'authentification pour le payeur, redirigez le payeur vers le serveur ACS en utilisant le champ
authentication.redirect.htmlfourni dans la réponse. Une fois l'authentification terminée, le serveur ACS redirige le payeur vers votre site Web et déclenche un rappel contenant les champs orderId, transactionId, response.gatewayRecommendation et result. Déterminez le résultat de l'authentification en fonction de la valeur renvoyée dans le champresponse.gatewayRecommendation. Les mêmes règles s'appliquent que celles décrites ci-dessus pour la réponseAUTHENTICATE PAYER(Authentifier le payeur). Si la recommandation est PROCEED, passez à l'étape 3.
Vous ne devez pas vous fier aux données renvoyées par le navigateur pour déterminer l'étape de traitement suivante. Assurez-vous de gérer la réponse Authenticate Payer (Authentifier le payeur) = sur votre serveur, ou d'effectuer une opération Retrieve Transaction (Extraire la transaction) à partir de votre serveur pour garantir le succès de la réponse.
Champs de réponse pour une demande authentifiée par mot de passe/certificat
Le tableau suivant répertorie les champs de réponse AUTHENTICATE PAYER (Authentifier le payeur) renvoyés pour une demande authentifiée par certificat/mot de passe, c'est-à-dire soumise avec un ID du commerçant et un mot de passe d'API provenant de votre serveur plutôt qu'avec un ID de session provenant de votre site Web ou du navigateur du payeur. Pour plus d'informations, voir Questions fréquentes.
Les champs marqués d'un * sont retourné en fonction de la version 3DS utilisée et du flux sans friction ou d'authentification. Par exemple,
authentication.3ds.authenticationToken n'est pas fourni si un flux sans friction est utilisé.Tableau : Champs de réponse pour une demande authentifiée par mot de passe/certificat
Response Field |
Authentifié par le commerçant |
|---|---|
| authentication.method | Oui |
| authentication.3ds.authenticationToken | * |
| authentication.3ds.acsEci | Oui |
| authentication.3ds.transactionId | Oui |
| authentication.3ds2.transactionStatus | * |
| authentication.3ds2.acsTransactionId | * |
| authentication.3ds2.dsTransactionId | * |
| authentication.3ds2.3dsServerTransactionId | * |
| authentication.3ds2.protocolVersion | * |
| authentication.amount | Oui |
| authentication.redirect.html | Oui |
| authentication.time | Oui |
| response.gatewayRecommendation | Oui |
| transaction.type | Oui |
| version | Oui |
| timeOfRecord | Oui |
| result | Oui |
| response.debugInformation | * |
Champs de la réponse Authenticate Payer (Authentifier le payeur)
Les champs retournés dans la réponse Authenticate Payer (Authentifier le payeur) dépendent :
- Du flux en vigueur, c'est-à-dire sans friction versus d'authentification.
- Comment la demande d'authentification a été lancée (authentication.channel)
- Mécanisme d'authentification soit pour la demande, session, certificat ou mot de passe.
Les champs suivants sont retournés pour une demande authentifiée par certificat/mot de passe. Pour une opération authentifiée par session, la réponse est filtrée pour supprimer les données qui ne sont pas liées au payeur et seuls les champs en liste blanche sont retournés. Pour plus d'informations, voir Authentification de session.
Response Field |
Authentifié par le commerçant |
|---|---|
| authentication.method | Oui |
| authentication.3ds.authenticationToken | * |
| authentication.3ds.acsEci | Oui |
| authentication.3ds.transactionId | Oui |
| authentication.3ds2.transactionStatus | * |
| authentication.3ds2.acsTransactionId | * |
| authentication.3ds2.dsTransactionId | * |
| authentication.3ds2.3dsServerTransactionId | * |
| authentication.3ds2.3dsServerTransactionId | * |
| authentication.3ds2.protocolVersion | * |
| authentication.amount | Oui |
| authentication.redirect.html | Oui |
| authentication.time | Oui |
| response.gatewayRecommendation | Oui |
| transaction.type | Oui |
| version | Oui |
| timeOfRecord | Oui |
| result | Oui |
| response.debugInformation | * |
* Le cas échéant, sur la base de la version de l'authentification 3DS et du flux (sans friction vs authentification, par exemple) en vigueur.
Exemple de demande Authenticate Payer (Authentifier le payeur)
| URL | https://na-gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| Méthode HTTP | PUT |
{
"authentication":{
"redirectResponseUrl":"<host>/merchantSimulator/jsp/simple/output.jsp"
},
"correlationId":"test",
"device": {
"browser": "MOZILLA",
"browserDetails": {
"3DSecureChallengeWindowSize": "FULL_SCREEN",
"acceptHeaders": "application/json",
"colorDepth": 24,
"javaEnabled": true,
"language": "en-US",
"screenHeight": 640,
"screenWidth": 480,
"timeZone": 273
},
"ipAddress": "127.0.0.1"
},
"order":{
"amount":"100",
"currency":"AUD"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"<card_number>",
"expiry":{
"month":"1",
"year":"39"
}
}
}
},
"apiOperation": "AUTHENTICATE_PAYER"
}
Exemple de réponse Authenticate Payer (Authentifier le payeur) - flux d'authentification
{
"authentication": {
"3ds": {
"transactionId": "a4d6ce7a-52ed-46c4-b1b8-0a64ffa3fdd8"
},
"3ds2": {
"3dsServerTransactionId": "cf976f0d-cb19-454f-a5b3-3cf09ae07e38",
"acsTransactionId": "c8027c6a-94da-480d-9270-85098bc680d5",
"directoryServerId": "A999999999",
"dsTransactionId": "a4d6ce7a-52ed-46c4-b1b8-0a64ffa3fdd8",
"methodSupported": "NOT_SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "test40Field@S^2sfds2ID",
"requestorName": "test40Field@S^2sfds2Name",
"sdk": {
"timeout": 400,
"uiType": "TEXT"
},
"transactionStatus": "C"
},
"amount": 100.00,
"method": "OUT_OF_BAND",
"payerInteraction": "REQUIRED",
"redirect": {
"customizedHtml": {
"3ds2": {
"acsUrl": "<acs_url>",
"cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNmOTc2ZjBkLWNiMTktNDU0Zi1hNWIzLTNjZjA5YWUwN2UzOCJ9"
}
},
"domainName": "<acs_domain>",
"html": "<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"style=\" height: 100vh\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"<acs_url>" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNmOTc2ZjBkLWNiMTktNDU0Zi1hNWIzLTNjZjA5YWUwN2UzOCJ9\" /> </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(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>"
},
"time": "2022-06-24T07:04:34.836Z",
"version": "3DS2"
},
"correlationId": "test",
"device": {
"browser": "mozilla",
"ipAddress": "127.0.0.1"
},
"merchant": "TEST3DS12AUTH",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"creationTime": "2022-06-24T07:03:43.780Z",
"currency": "USD",
"id": "TEST6",
"lastUpdatedTime": "2022-06-24T07:04:34.795Z",
"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": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"number": "512345xxxxxx8212",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-06-24T07:04:34.795Z",
"timeOfRecord": "2022-06-24T07:03:43.780Z",
"transaction": {
"acquirer": {
"merchantId": "123456"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"currency": "USD",
"id": "1",
"type": "AUTHENTICATION"
},
"version": "67"
}
Étape 3 : Utiliser le résultat de l'authentification dans un paiement
Lorsque le résultat de l'opération AUTHENTICATE PAYER (Authentifier le payeur) indique que vous pouvez poursuivre avec le paiement response.gatewayRecommendation=PROCEED, vous pouvez initier une opération Authorize (Autoriser) ou PAY (Payer). En plus des champs standard, vous devez renseigner les champs suivants :
order.id: Utilisez le mêmeorder.idque vous avez fourni dans les opérationsINITIATE AUTHENTICATION(Initier l'authentification) etAUTHENTICATE PAYER(Authentifier le payeur).authentication.transactionId: Utilisez le mêmetransaction.idque vous avez fourni dans les opérationsINITIATE AUTHENTICATION(Initier l'authentification) etAUTHENTICATE PAYER(Authentifier le payeur). Il n'est pas nécessaire d'inclure les champs dans l'objetauthentication, car la passerelle utiliseauthentication.transactionIdpour 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.
Exemple de demande PAY (Payer)
| URL | https://na-gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| Méthode HTTP | PUT |
{
"apiOperation":"PAY",
"authentication":{
"transactionId":"<your_transaction_ID>"
},
"order":{
"amount":"100",
"currency":"AUD",
"reference":"<your_order_ID>"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"<card_number>",
"expiry":{
"month":"1",
"year":"39"
}
}
},
"type":"CARD"
},
"transaction":{
"reference":"<your_order_ID>"
}
}
Exemple de réponse PAY (Payer)
{
"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"
}
Questions fréquentes
Puis-je utiliser l'API Payer Authentication (Authentification du payeur) comme API côté client ?
Vous pouvez utiliser l'API Payer Authentication (Authentification du payeur) comme API côté serveur ou comme API côté client sur votre site Web ou dans le navigateur du payeur.
- API côté client : vous devez tout d'abord établir le canal d'authentification par lequel votre serveur de commerçant doit communiquer avec le serveur de la passerelle pour créer la session sur la passerelle. Une fois la session créée, vous pouvez l'utiliser pour authentifier toutes les opérations API ultérieures nécessaires à la gestion des flux d'intégration 3DS directement depuis le navigateur à l'aide de l'API JavaScript 3DS ou à l'aide de votre propre bibliothèque.
- API côté serveur : vous devez effectuer toutes les opérations nécessaires à la gestion des flux d'intégration 3DS directement depuis votre serveur de commerçant vers le serveur de la passerelle. Vous pouvez prendre en charge tous les modes de transaction d'authentification via l'API Payer Authentication (Authentification du payeur).
- En mode Authentification uniquement, utilisez les opérations
INITIATE AUTHENTICATION(Initier l'authentification) etAUTHENTICATE PAYER(Authentifier le payeur). Authentication Only (Authentification uniquement) : exécuter les opérations Initiate Authentication (Initier l'authentification) et Authenticate Payer (Authentifier le payeur). - En mode Transaction d'authentification et de paiement), utilisez les opérations
INITIATE AUTHENTICATION(Initier l'authentification),AUTHENTICATE PAYER(Authentifier le payeur) et AUTHORIZE/PAY (Autoriser/Payer). - En mode Transaction de paiement pré-authentifiée, utilisez les opérations AUTHORIZE/PAY (Autoriser/Payer) en utilisant les détails de l'authentification d'un prestataire externe.
- En mode Authentification uniquement, utilisez les opérations
Pour plus d'informations sur les questions fréquentes d'ordre général sur 3-D Secure, voir Questions fréquentes.