- 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 enregistré 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 commande.sourceOfFunds.provided.card.*ousession.idousourceOfFunds.token: détails de la carte utilisée pour le paiement.Jetons de réseau
La passerelle peut traiter les jetons de réseau dans la demande Check 3DS Enrollment (Vérifier l'inscription à 3DS). Les jetons de réseau obtenus auprès des prestataires de services de segmentation en jetons Mastercard Digital Enablement Service (MDES) et Visa Token Service (VTS) sont actuellement pris en charge.
Si vous avez obtenu un jeton de réseau en vous intégrant directement au service de segmentation en jetons de réseau, vous devez fournir les détails du jeton à l'aide des champs suivants (les jetons MDES sont pris en charge à compter de DirectAPI v54 et les jetons VTS sont pris en charge à compter de DirectAPI v55) :
sourceOfFunds.type=SCHEME_TOKEN: permet à la passerelle d'identifier la source des fonds fournie dans la demande en tant que jeton de réseau.sourceOfFunds.provided.card.number: jeton de réseau. Indiquez la valeur du « Token PAN » MDES ou du « Token » VTS.sourceOfFunds.provided.card.expiry: (facultatif) expiration du jeton de réseau.
Si vous avez été activé pour la segmentation en jetons de réseau par votre your payment service provider, toute demande adressée à la passerelle pour un jeton de passerelle tentera également de générer un jeton de réseau correspondant. La passerelle tentera également la segmentation en jetons de réseau pour toutes les cartes applicables déjà stockées dans le référentiel de jetons de la passerelle. La demande Check 3DS Enrollment (Vérifier l'inscription à 3DS) utilise le jeton de réseau s'il est disponible, sinon le PAN de financement (FPAN) stocké sur le jeton de passerelle est utilisé (les jetons MDES pris en charge à compter de DirectAPI v55 et les jetons VTS pris en charge à compter de DirectAPI v56).
- (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.
La passerelle renvoie les résultats du contrôle de l'inscription dans la réponse :
3DSecure.xid: identifiant de transaction unique généré par Mastercard Gateway pour l'authentification 3DS.3DSecure.veResEnrolled: indique si l'authentification du payeur est disponible pour le numéro de carte.
La passerelle renvoie également response.gatewayRecommendation, que vous pouvez utiliser pour déterminer l'étape suivante. Cette recommandation est basée sur les règles de filtrage des transactions 3DS configurées par vous ou votre your payment service provider.
response.gatewayRecommendation |
Étape suivante |
|---|---|
| PROCEED | Vous pouvez poursuivre l'authentification du payeur. |
| DO_NOT_PROCEED | Ne pas poursuivre l'authentification 3DS pour cette carte. Vous pouvez proposer au payeur d'essayer un autre mode de paiement. |
Pour une intégration avancée, vous pouvez déterminer l'étape suivante à l'aide de la valeur renvoyée dans le champ 3DSecure.veResEnrolled. Le tableau ci-dessous en présente le résumé. Reportez-vous à la documentation du système de cartes pour interpréter le champ « inscrit » dans le message Verify Enrollment Response (VERes) (Vérifier la réponse d'inscription).
3DSecure.veResEnrolled |
Étape suivante |
|---|---|
| Carte inscrite | La carte est inscrite à 3DS. Poursuivez l'authentification du payeur. |
| Carte non inscrite | La carte n'est pas inscrite à 3DS. Poursuivez l'opération de paiement en indiquant le champ 3DSecureId sur la demande. |
| La carte ne prend pas en charge 3DS | La carte ne prend pas en charge 3DS et vous ne pouvez pas poursuivre l'authentification 3DS. |
| Authentification non disponible | Une erreur s'est produite. Poursuivez l'opération de paiement en indiquant le champ 3DSecureId sur la demande. |
Référence de l'API Check 3DS Enrollment (Vérifier l'inscription à 3DS) [REST] [NVP]
Si la carte est inscrite, (par exemple, 3DSecure.veResEnrolled = Y), 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 la réponse PARes dans le champ 3DSecure.paRes sur l'opération Process ACS Result (Traiter le résultat ACS) et soumettez l'opération. La passerelle indique les résultats de l'authentification dans la réponse :
3DSecure.veResEnrolled: indique si l'authentification du payeur est disponible pour le numéro de carte.3DSecure.paResStatus: indique le résultat de l'authentification du payeur avec l'émetteur. Si le paramètre PaRes n'est pas valide, ce champ n'est pas retourné. Voir la documentation du système de cartes appropriée pour déterminer l'étape suivante.
La passerelle renvoie également response.gatewayRecommendation, que vous pouvez utiliser pour 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.
response.gatewayRecommendation |
Étape suivante |
|---|---|
| PROCEED | Vous pouvez poursuivre l'opération de paiement en indiquant le champ 3DSecureId sur la demande. |
| DO_NOT_PROCEED | Ne pas passer à la soumission d'une opération de paiement. Vous pouvez proposer au payeur d'essayer un autre mode de paiement. |
Pour une intégration avancée, vous pouvez déterminer l'étape suivante à l'aide de la valeur renvoyée dans le champ 3DSecure.paResStatus. Le tableau ci-dessous en présente le résumé. Voir la documentation du système de cartes pour interpréter le champ « statut » dans le message PARes.
3DSecure.paResStatus |
Étape suivante |
|---|---|
| Authentification réussie | L'authentification du payeur s'est correctement déroulée. Poursuivez l'opération de paiement en indiquant le champ 3DSecureId sur la demande. |
| Échec de l'authentification | L'authentification du payeur a échoué. Vous ne devez pas poursuivre l'opération de paiement. Cela contrevient aux règles du réseau. |
| Tentative d'authentification | Une tentative d'authentification du payeur a eu lieu, mais elle n'a pas abouti. Poursuivez l'opération de paiement en indiquant le champ 3DSecureId sur la demande. |
| Authentification non disponible | Une erreur s'est produite. Poursuivez l'opération de paiement en indiquant le champ 3DSecureId sur 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 est inutile d'inclure des paramètres dans le groupe de paramètres 3DSecure, car la passerelle utilise le champ 3DSecureId pour rechercher les résultats de l'authentification stockés lorsque vous lui demandez de traiter ces résultats. La passerelle transmet les informations demandées à l'acquéreur.
result = ERROR dans la réponse à l'opération de paiement. Vous pouvez proposer au payeur d'essayer un autre mode de paiement.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 la vérification de 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 HTML 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: 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 d'authentification de l'opération Pay (Payer) ou Authorize (Autoriser).
Tous les champs sont facultatifs et le fait qu'ils vous soient fournis ou non par le MPI 3DS externe dépend du statut d'authentification de la transaction. Cependant, si vous disposez de ces données, il est recommandé de les fournir.
authentication.3ds.acsEci: indicateur de commerce électronique qui peut vous être renvoyé dans le message de réponse d'authentification.authentication.3ds.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.authentication.3ds.transactionId: Un identifiant de transaction unique généré par la passerelle pour l'authentification 3DS. Ce champ correspond à XID, qui est un identifiant généré par la passerelle pour le compte du commerçant. Un XID soumis dans ce champ doit être au format base64.authentication.3ds1.paResStatus:Indique le résultat de l'authentification du payeur avec l'émetteur.authentication.3ds1.veResEnrolled:Indique si l'authentification du payeur est disponible ou non pour le numéro de carte que vous avez fourni.
authentication.3ds.authenticationToken.Référence de l'API Pre-authenticated 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
La passerelle fournit le statut d'inscription et le statut d'authentification dans les champs 3DSecure.veResEnrolled et 3DSecure.paResStatus, respectivement.
Le message VERes est le message renvoyé à la passerelle par le système de cartes en réponse à une demande Check 3DS Enrollment (Vérifier l'inscription à 3DS). La réponse d'authentification du paiement (PARes) est le message renvoyé à la passerelle en réponse à une demande d'authentification du payeur.
Reportez-vous à la documentation du système de cartes pour interpréter les valeurs retournées dans les champs 3DSecure.veResEnrolled et 3DSecure.paResStatus.
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 de recherche Authentifications dans Merchant Administration.
Oui, vous pouvez contourner l'authentification 3DS pour les payeurs pour lesquels les paiements sont considérés comme étant à risque faible par le prestataire de services de gestion des risques externes. Pour plus d'informations, voir Authentification 3DS dynamique.
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.paResStatus).