- Directives d'intégration
- Fonctionnalités prises en charge (Sécurité)
- Authentification 3-D Secure
Authentification 3-D Secure
L'authentification 3-Domain Secure™ (3-D Secure ou 3DS) est conçue pour protéger les achats en ligne contre la fraude à la carte de crédit en vous permettant d'authentifier le payeur avant de soumettre une transaction Authorization (Autorisation) ou Pay (Payer). Selon le principe de l'authentification 3DS, le payeur est redirigé vers l'émetteur de sa carte et entre un mot de passe enregistré précédemment.
Mastercard Gateway prend en charge l'authentification 3DS utilisant Mastercard SecureCode™, Verified by Visa™, J/Secure™, American Express SafeKey™ et Diners Club ProtectBuy™.
Conditions préalables
- Vous devez être inscrit auprès de votre acquéreur pour utiliser 3DS
- Un schéma 3DS doit être activé sur votre profil de commerçant dans Mastercard Gateway.
Expérience du payeur 3DS
Cette rubrique fournit un exemple de flux de paiement pour le site de votre magasin, dans lequel le payeur est authentifié au moyen de 3DS.
Le flux de paiement d'une authentification réussie est le suivant :
- Un payeur navigue sur le site de votre magasin, sélectionne un ou plusieurs produits, accède à la page de paiement et choisit de payer avec une carte qui prend en charge 3DS.
- Check 3DS Enrollment (Vérifier l'inscription à 3DS) : vous demandez à Mastercard Gateway de vérifier auprès du système de cartes si la carte est inscrite à 3DS.
- Authentifier le payeur : après avoir vérifié que la carte est inscrite, vous redirigez le navigateur du payeur vers la page d'authentification 3DS de l'émetteur. Le payeur entre son mot de passe 3DS et soumet les informations. L'émetteur vous renvoie le résultat de l'authentification.
- Traiter le résultat ACS : vous demandez au Mastercard Gateway de traiter le résultat de l'authentification. Mastercard Gateway vous fournit les détails de la réponse d'authentification reçue de l'émetteur.
- Utilisation des résultats 3DS dans une opération de paiement : vous soumettez le paiement pour traitement
- Vous affichez la page de confirmation de commande au payeur.
Intégration pour utiliser l'authentification 3DS
Cette rubrique explique comment intégrer Mastercard Gateway pour utiliser 3DS.
Vous pouvez vérifier si une carte est inscrite en fournissant les champs suivants dans la demande Check 3DS Enrollment (Vérifier l'inscription à 3DS) :
3DSecureId: Votre identifiant unique pour cette authentification. Vous devez inclure ce même identifiant dans toutes les opérations ultérieures.3DSecure.authenticationRedirect.responseUrl: URL vers laquelle rediriger le payeur une fois le processus d'authentification 3DS terminéorder.amount: montant total de la commandeorder.currency: devise de la commandesourceOfFunds.provided.cardousession.idousourceOfFunds.token: détails de la carte utilisée pour le paiement- (Facultatif)
3DSecure.goodsDescription: vous pouvez fournir une brève description des marchandises achetées. Si elle est prise en charge par le serveur de contrôle d'accès de l'émetteur, cette description sera affichée sur la page d'authentification présentée au payeur.
Mastercard Gateway indique les résultats de la vérification de l'inscription dans la réponse :
3DSecure.xid: Identifiant de transaction unique généré par Mastercard Gateway pour l'authentification 3DS.3DSecure.summaryStatus: réponse résumée indiquant le statut d'inscription global de la carteresponse.3DSecure.gatewayCode: réponse détaillée décrivant le statut d'inscription de la carte
Pour déterminer l'étape suivante, voir 3DSecure.summaryStatus. Ceci est résumé dans le tableau ci-dessous :
| 3DSecure.summaryStatus | Étape suivante |
|---|---|
| CARD_ENROLLED | La carte est inscrite à 3DS. Poursuivez l'authentification du payeur. |
| CARD_NOT_ENROLLED | La carte n'est pas inscrite à 3DS. Poursuivez l'opération de paiement en incluant le 3DSecureID dans la demande |
| CARD_DOES_NOT SUPPORT_3DS | La carte ne prend pas en charge 3DS et vous ne pouvez pas poursuivre l'authentification 3DS. |
| AUTHENTICATION_NOT_AVAILABLE | Une erreur s'est produite. Poursuivez l'opération de paiement, en incluant le champ 3DSecureID dans la demande. |
Référence de l'API Check 3DS Enrollment (Vérifier l'inscription 3DS) [REST] [NVP]
Si la carte est inscrite, (response.3DSecure.gatewayCode = CARD_ENROLLED), vous devez rediriger le navigateur du payeur vers le site Web de l'émetteur de la carte pour authentification. Renvoyez simplement le contenu fourni dans 3DSecure.authenticationRedirect.simple.htmlBodyContent au navigateur du payeur.
Lorsque le processus d'authentification est terminé sur le site Web de l'émetteur, le serveur de contrôle d'accès de l'émetteur vous renvoie la réponse d'authentification sous la forme d'un HTTP POST à l'URL de réponse (3DSecure.authenticationRedirect.responseUrl) que vous avez spécifiée dans la demande Check 3DS Enrollment (Vérifier l'inscription à 3DS).
La réponse d'authentification du paiement (PARes) qui vous a été renvoyée est fournie en tant que valeur codée en base64. Pour décoder cette valeur, transférez les réponses PARes vers le champ 3DSecure.paRes de l'opération Process ACS Result (Traiter le résultat ACS) et soumettez l'opération. Mastercard Gateway indique les résultats de l'authentification dans la réponse :
3DSecure.summaryStatus: réponse résumée indiquant le statut d'authentification globalresponse.3DSecure.gatewayCode: Une réponse détaillée décrivant le statut d'authentification
Vous devriez examiner response.3DSecure.summaryStatus pour déterminer la prochaine étape à suivre. Ceci est résumé dans le tableau ci-dessous :
| 3DSecure.summaryStatus | Étape suivante |
|---|---|
| AUTHENTICATION_SUCCESSFUL | L'authentification du payeur s'est correctement déroulée. Poursuivez l'opération de paiement, en incluant le 3DSecureID dans la demande. |
| AUTHENTICATION_FAILED | L'authentification du payeur a échoué. Vous ne devez pas poursuivre l'opération de paiement. Cela contrevient aux règles du réseau. |
| AUTHENTICATION_ATTEMPTED | Une tentative d'authentification du payeur a eu lieu, mais elle n'a pas abouti. Poursuivez l'opération de paiement, en incluant le 3DSecureID dans la demande. |
| AUTHENTICATION_NOT_AVAILABLE | Une erreur s'est produite. Poursuivez l'opération de paiement, en incluant le champ 3DSecureID dans la demande. |
Référence de l'API Process ACS Result (Traiter les résultats ACS) [REST] [NVP]
Lorsque le résultat de l'opération Check 3DS Enrollment (Vérifier l'inscription à 3DS) ou de traitement ACS indique que vous pouvez poursuivre le paiement, vous pouvez lancer une opération Authorize (Autoriser) ou Pay (Payer). Incluez dans la demande le champ 3DSecureId que vous avez indiqué dans l'opération Check 3DS Enrollment (Vérifier l'inscription à 3DS). Il n'est pas nécessaire d'inclure de paramètres du groupe de paramètres 3DSecure, car Mastercard Gateway utilisera le champ 3DSecureId pour retrouver les résultats d'authentification qu'il a stockés lorsque vous lui avez demandé de traiter le résultat d'authentification. Mastercard Gateway acheminera les informations obligatoires à l'acquéreur.
Référence de l'API 3DSecureId on Authorize (3DSecureId sur une opération Authorize [Autoriser]) [REST] [NVP]
Référence de l'API 3DSecureId on Pay (3DSecureId sur une opération Pay [Payer]) [REST] [NVP]
Autres options
Avant de vérifier l'inscription à 3DS, vous pouvez soumettre une demande d'évaluation du taux pour la conversion de devise dynamique (CDD) afin d'extraire la devise du payeur et le montant de la commande dans cette devise. Si le payeur accepte l'offre CDD, vous devez inclure les informations CDD dans la demande Check 3DS Enrollment (Vérifier l'inscription à 3DS).
Référence de l'API DCC on Check 3DS Enrollment (DCC lors de l'opération Check 3DS Enrollment [Vérifier l'inscription à 3DS]) [REST] [NVP]
Le code HTML requis pour le formulaire permettant de rediriger le payeur en vue de l'authentification peut être généré au moyen de l'une des deux méthodes de génération de page suivantes :
Simple: Mastercard Gateway génère le formulaire HTML. Le formulaire complet est renvoyé dans la réponse Check 3DS Enrollment (Vérifier l'inscription à 3DS). Il s'agit de l'option par défaut.Customized: vous générez votre propre formulaire HTM personnalisé au moyen des paramètres fournis dans la réponse Check 3DS Enrollment (Vérifier l'inscription à 3DS).
La réponse à l'opération Check 3DS Enrollment (Vérifier l'inscription à 3DS) comprend les informations requises pour l'option sélectionnée.
(Facultatif) Personnalisez le formulaire simple
Vous pouvez personnaliser le formulaire simple généré en définissant 3DSecure.authenticationRedirect.pageGenerationMode = SIMPLE dans la demande Check 3DS Enrollment (Vérifier l'inscription à 3DS) et en spécifiant des valeurs pour un ou plusieurs paramètres :
3DSecure.authenticationRedirect.simple.expectedHtmlEncoding3DSecure.authenticationRedirect.simple.redirectDisplayBackgroundColor3DSecure.authenticationRedirect.simple.redirectDisplayContinueButtonText3DSecure.authenticationRedirect.simple.redirectDisplayTitle
(Facultatif) Générez votre propre formulaire personnalisé
Vous pouvez indiquer que vous voulez générer votre propre formulaire en définissant 3DSecure.authenticationRedirect.pageGenerationMode = CUSTOMIZED dans la demande Check 3DS Enrollment (Vérifier l'inscription à 3DS). La réponse inclut les paramètres suivants :
3DSecure.authenticationRedirect.customized.acsUrl: URL du serveur de contrôle d'accès de l'émetteur sur lequel le payeur peut être authentifié.3DSecure.authenticationRedirect.customized.paReq: Le message de demande d'authentification du payeur (PAReq) à envoyer à l'ACS pour lancer l'authentification du payeur.
Incluez ces valeurs dans votre formulaire avec l'URL vers laquelle renvoyer le payeur une fois l'authentification terminée.
Vous trouverez ci-dessous un exemple de formulaire personnalisé.
<!-- Populate the form action attribute with the value returned in the 3DSecure.authenticationRedirect.customized.acsUrl response parameter -->
<form name="3dsRedirect" action="[3DSecure.authenticationRedirect.customized.acsUrl]" method="POST" accept-charset="UTF-8">
<!-- Populate the mandatory PaReq parameter with the value returned in the 3DSecure.authenticationRedirect.customized.paReq response parameter. -->
<input type="hidden" name="PaReq" value="[3DSecure.authenticationRedirect.customized.paReq]"/>
<!-- Populate the mandatory TermUrl value with the URL to which you want the payer returned when the authentication process has completed. This should be the same value as supplied in the 3DSecure.authenticationRedirect.responseUrl parameter to the CHECK_ENROLLMENT request. -->
<input type="hidden" name="TermUrl" value="https://merchant.com/3ds/return"/>
<!-- The ACS will echo the contents of the mandatory MD parameter when the payer is returned to the URL specified in the TermUrl parameter. You can use this parameter to establish a link between the ACS request and response. -->
<input type="hidden" name="MD" value="[mdvalue]"/>
<input type="submit" value="Click here to continue" class="button">
</form>
Référence de l'API (Customize Form on Check 3DS Enrollment) Personnaliser le formulaire lors de la vérification de l'inscription à 3DS [REST] [NVP]
Si vous avez utilisé un MPI 3DS externe pour authentifier le payeur, vous devez transmettre les informations relatives à l'authentification dans le groupe de paramètres 3DSecure de l'opération Pay (Payer) ou Authorize (Autoriser).
Il y a un champ obligatoire :
3DSecure.enrollmentStatus: Indique si le titulaire de la carte est inscrit à 3DS. ce champ est obligatoire
Les autres champs sont facultatifs, car le fait qu'ils vous aient été fournis ou non par le MPI 3DS externe dépend du statut d'authentification de la transaction :
3DSecure.authenticationStatus:indique si l'authentification 3DS du payeur s'est correctement déroulée.3DSecure.authenticationToken: valeur codée en base64, générée par l'émetteur de la carte, qui peut vous être renvoyée dans le message de réponse d'authentification.3DSecure.acsEci: L'indicateur de commerce électronique qui peut vous être renvoyé dans le message de réponse d'authentification.3DSecure.xid: identifiant de transaction unique de l'authentification 3DS.
3DSecure.summaryStatus = AUTHENTICATION_ATTEMPTED, vous fournissiez 3DSecure.authenticationToken.Référence de l'API Preauthenticated 3DS on Authorize (3DS préauthentifié sur une opération Authorize [Autoriser]) [REST] [NVP]
Référence de l'API Preauthenticated 3DS on Pay (3DS préauthentifié sur une opération Pay [Payer]) [REST] [NVP]
Si vous souhaitez extraire les résultats de l'authentification à une étape quelconque, utilisez l'opération Retrieve 3DS Result (Extraire les résultat 3DS).
Référence de l'API Retrieve 3DS Result (Extraction de résultat 3DS) [REST] [NVP]
Questions fréquentes
Mastercard Gateway affiche un résumé du statut d'authentification dans le champ response.3DSecure.gatewayCode. Si vous souhaitez dériver les valeurs des champs 3DS utilisés pour traiter un paiement, vous pouvez le faire à partir du champ response.3DSecure.gatewayCode.
| response.3DSecure.gatewayCode | 3DSecure.enrollmentStatus | 3DSecure.authenticationStatus | Soumettre une opération de paiement |
|---|---|---|---|
| CARD_ENROLLED | ENROLLED | - | (Procéder à l'authentification) |
| NOT_ENROLLED_NO_ERROR_DETAILS | NOT_ENROLLED | - | Oui |
| NOT_ENROLLED_ERROR_DETAILS_PROVIDED | NOT_ENROLLED | - | Oui |
| ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS | ENROLLMENT_STATUS_UNDETERMINED | - | Oui |
| ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED | ENROLLMENT_STATUS_UNDETERMINED | - | Oui |
| AUTHENTICATION_SUCCESSFUL | ENROLLED | AUTHENTICATION_SUCCESSFUL | Oui |
| AUTHENTICATION_ATTEMPTED | ENROLLED | AUTHENTICATION_ATTEMPTED | Oui |
| AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS | ENROLLED | AUTHENTICATION_NOT_AVAILABLE | Oui |
| AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED | ENROLLED | AUTHENTICATION_NOT_AVAILABLE | Oui |
| AUTHENTICATION_FAILED | ENROLLED | AUTHENTICATION_FAILED | Non (non autorisé) |
| MPI_PROCESSING_ERROR | ENROLLED | - | Oui |
| ACS_SESSION_TIMEOUT | ENROLLED | - | Oui |
| ERROR_PARSING_AUTHENTICATION_RESPONSE | ENROLLED | - | Non (échec) |
| INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE | ENROLLED | - | Non (échec) |
| CARD_DOES_NOT_SUPPORT_3DS | - | - | Non (échec) |
| ERROR_PARSING_CHECK_ENROLLMENT_REQUEST | - | - | Non (échec) |
| INVALID_DIRECTORY_SERVER_CREDENTIALS | - | - | Oui (sans données 3DS) |
| ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE | - | - | Oui (sans données 3DS) |
| ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER | - | - | Oui (sans données 3DS) |
Si nécessaire, vous pouvez dériver la valeur VERes.enrolled de 3DSecure.enrollmentStatus :
| VERes.enrolled | 3DSecure.enrollmentStatus |
|---|---|
| Y | ENROLLED |
| N | NOT_ENROLLED |
| U | ENROLLMENT_STATUS_UNDETERMINED |
Vous pouvez également dériver la valeur PAREs.status de 3DSecure.authenticationStatus :
| PARes.statut | 3DSecure.authenticationStatus |
|---|---|
| Y | AUTHENTICATION_SUCCESSFUL |
| N | AUTHENTICATION_FAILED |
| U | AUTHENTICATION_NOT_AVAILABLE |
| A | AUTHENTICATION_ATTEMPTED |
Si vous avez soumis des détails 3DS sur une transaction, recherchez la commande ou la transaction dans Merchant Administration. Affichez les détails de la commande, puis sélectionnez le lien pour afficher les détails de l'authentification.
Si vous souhaitez afficher les détails d'une authentification pour laquelle vous n'avez pas procédé au paiement (par exemple, l'authentification a échoué), utilisez l'option Recherche d'authentification de paiement dans Merchant Administration.
Le code État de l'authentification affiché lorsque vous consultez les détails de l'authentification dans Merchant Administration peut être mappé avec response.3DSecure.gatewayCode. Reportez-vous aux nouveaux codes dans le tableau ci-dessous :
| Client de paiement/Client de paiement virtuel | DirectAPI | |
|---|---|---|
| Nouveaux codes | Anciens codes | response.3DSecure.gatewayCode |
| E | E | NOT_ENROLLED_NO_ERROR_DETAILS |
| Z | NOT_ENROLLED_ERROR_DETAILS_PROVIDED |
|
| C | C | CARD_DOES_NOT_SUPPORT_3DS |
| B | U | ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS |
| V | ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED |
|
| F | F | ERROR_PARSING_CHECK_ENROLLMENT_REQUEST |
| A | A | INVALID_DIRECTORY_SERVER_CREDENTIALS |
| W | U | ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE |
| D | D | ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER |
| I | I | MPI_PROCESSING_ERROR |
| P | P | ERROR_PARSING_AUTHENTICATION_RESPONSE |
| S | S | INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE |
| T | T | ACS_SESSION_TIMEOUT |
| X | U | AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS |
| U | AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED |
|
| Y | Y | AUTHENTICATION_SUCCESSFUL |
| N | N | AUTHENTICATION_FAILED |
| M | M | AUTHENTICATION_ATTEMPTED |
| R | CARD_ENROLLED |
|
Vous pouvez tester votre intégration du processus d'authentification 3DS par Mastercard Gateway à l'aide de l'émulateur ACS. Cela vous permet de sélectionner un résultat d'authentification 3DS précis (qui est retourné dans la réponse de transaction dans le champ 3DSecure.authenticationStatus).
Le test est pris en charge pour les systèmes d'authentification 3D-Secure suivants :
- Mastercard SecureCode
- Verified by Visa
- American Express SafeKey
- J/Secure
- Diners ProtectBuy
Pour tester la fonctionnalité d'authentification 3D-Secure :
- Utilisez une carte de test inscrite à 3-D Secure (voir les cartes répertoriées dans les sections concernant les acquéreurs spécifiques) lorsque vous soumettez une demande
CHECK_3DS_ENROLLMENTpour votre profil de test de commerçant. - Vérifiez que vous recevez une réponse avec
response.3DSecure.gatewayCode=CARD_ENROLLED. - Utilisez le formulaire fourni dans
3DSecure.authenticationRedirect.simple.htmlBodyContentpour rediriger le navigateur du payeur vers la page de l'émulateur ACS.L'émulateur ACS redirige le navigateur du payeur vers votre site Web et contient le PARes.
- Soumettez une demande
PROCESS_ACS_RESULTavec le PARes dans3DSecure.paRes. - Utilisez l'ID pour cette authentification 3D-Secure via Mastercard Gateway, fourni dans le champ
3DSecureIddans une demande de transaction ultérieure (par exemplePAYouAUTHORIZE).