- Directives d'intégration
- Fonctionnalités prises en charge (Sécurité)
- Sécurisation de votre intégration avec des mots de passe ou des certificats
Sécurisation de votre intégration avec des mots de passe ou des certificats
Vous pouvez vous authentifier sur Mastercard Gateway à l'aide de mots de passe ou de certificats SSL.
Authentification par mot de passe
Vous pouvez activer l'accès sécurisé aux intégrations Mastercard GatewayDirectAPI et Batch via des mots de passe. Le mot de passe généré par le système est une valeur de 16 octets générée de manière aléatoire et codée sous forme de chaîne hexadécimale. Bien que sa longueur et sa qualité soient suffisantes pour résister à la détection par force brute, il doit être sécurisé de la même manière que les mots de passe utilisateur et les autres données sensibles.
Génération d'un mot de passe pour DirectAPI
Vous pouvez générer votre mot de passe API dans Merchant Administration. Votre profil de commerçant doit au préalable être activé pour l'API, Batch et le privilège « Utiliser l'authentification par mot de passe ».
Pour accéder à Merchant Administration, vous avez besoin de vos identifiants de connexion. Les identifiants de connexion de l'administrateur vous seront indiqués par your payment service provider lorsque vous vous serez connecté avec succès à la passerelle. En tant qu'administrateur, vous pouvez créer un nouvel opérateur avec des autorisations pour générer le mot de passe d'API.
- Connectez-vous à https://ap-gateway.mastercard.com/ma avec vos identifiants de connexion administrateur.
- Accédez à Administrateur > Opérateurs.
- Créez un nouvel opérateur en renseignant tous les champs obligatoires. Affectez privilège « Peut configurer les paramètres d'intégration » pour permettre aux opérations de générer le mot de passe d'API.
- Déconnectez-vous de Merchant Administration et reconnectez-vous à Merchant Administration en tant que nouvel opérateur.
- Accédez à Admin > Paramètres d'intégration de l'API > Modifier.
- Cliquez sur Générer nouveau et cochez la case Activer l'accès à l'intégration via un mot de passe.
- Il s'agit du mot de passe d'API que vous utiliserez pour authentifier les requêtes API effectuées depuis votre serveur Web vers la passerelle.
- Cliquez sur Soumettre.
Vous devez toujours avoir au moins un mot de passe généré et activé, mais vous pouvez en avoir jusqu'à deux configurés. Par mesure de sécurité, vous devez modifier le mot de passe périodiquement. Un seul mot de passe doit être utilisé pour configurer votre application. Le second sert de réserve, à des fins de rotation de mots de passe.
Une fois le mot de passe généré, vous devez l'inclure dans toutes les demandes de transaction adressées à Mastercard Gateway. Si la demande est envoyée avec le protocole REST-JSON, elle doit contenir l’ID utilisateur et le mot de passe dans l’en-tête d’authentification de base HTTP standard. Avec NVP, vous devez indiquer des paramètres supplémentaires dans la demande, apiUsername
et apiPassword
, afin d'utiliser l'API.
Pour vous authentifier en tant que commerçant, le nom (apiUsername
pour NVP et ID utilisateur pour REST-JSON) et le mot de passe (apiPassword
pour NVP et mot de passe REST-JSON) doivent contenir « merchant.<your gateway merchant ID> » et le mot de passe généré par le système, respectivement.
Référence de l'API Password (Mot de passe) [REST][NVP]
Authentification par certificat
Notez que le nom d'hôte pour l'authentification par certificat est différent de https://ap-gateway.mastercard.com/api. Veuillez contacter your payment service provider pour le nom d'hôte.
Avec l’authentification par certificat, vous devez présenter un certificat pour vous authentifier auprès de Mastercard Gateway. Les certificats sont généralement émis par l’une des différentes organisations qui interviennent comme autorités de certification (CA). Ce modèle d’authentification est un composant de la PKI (Public Key Infrastructure) dans laquelle la sécurité est réalisée via la confidentialité, l’intégrité, la non-répudiation et l’authentification. La CA affirme que la clé publique liée au certificat est correcte, appartient à la personne ou à l’entité déclarée (c’est-à-dire qu’elle est authentique) et n’a pas fait l’objet d’une fraude ou n’a pas été remplacée par un tiers malveillant.
Le mécanisme d’authentification pour l’authentification par certificat exige que le client (votre serveur Web) et le serveur (le serveur HTTP Mastercard Gateway) présentent des certificats pour s’authentifier. C’est ce que l’on nomme l’authentification mutuelle, dont le flux de fonctionnement est illustré ci-dessous.
Lorsque vous vous connectez à Mastercard Gateway en utilisant l’authentification par certificat, voici ce qui se produit :
- Le client demande la connexion à une ressource protégée sur le serveur. Ceci se produit pour chaque demande de transaction lancée par le client.
- Le serveur présente sa chaîne de certificats au client.
- Le client vérifie le certificat du serveur en utilisant un magasin approuvé, qui contient les CA racines approuvées. Le client valide le chemin du certificat vers un certificat racine de CA approuvé.
- En cas de réussite, le client envoie sa chaîne de certificats au serveur, qui est contenue dans un magasin de clés.
- Le serveur vérifie le certificat du client en utilisant l’ensemble des certificats racines de CA approuvés/de confiance qui sont chargés sur le serveur. Les contrôles suivants sont réalisés :
- Contrôle de la conformité du certificat au format X.509.
- Validation du chemin du certificat vers un certificat racine de CA approuvé.
- Exécution d’un contrôle CRL ou OCSP (Online Certificate Status Protocol) pour s’assurer que le certificat n’a pas été révoqué.
- Contrôle de la non-expiration du certificat.
Une fois que le serveur HTTP a validé avec succès le certificat client, la chaîne de certificats complète du client est transmise à DirectAPI pour vérification. Dans le cas contraire, le serveur HTTP retourne des messages d’erreur de certificat SSL standard.
La vérification intervient au niveau du serveur HTTP et au niveau de DirectAPI. Le serveur HTTP effectue une validation complète du certificat SSL et DirectAPI effectue une authentification du certificat au niveau de l’entreprise. - DirectAPI réalise les contrôles suivants :
- Extraction du nom commun de sujet du certificat client et vérification de la correspondance avec le nom commun de sujet enregistré pour le commerçant dans la base de données. Le nom commun de sujet du certificat doit contenir le nom d’entreprise légal du commerçant.
- Vérification que le certificat client contient une extension Key-Usage, marquée comme critique, qui comprend l’authentification du client comme utilisation autorisée du certificat.
- Validation simple du certificat du client par rapport à un certificat racine de CA contenu dans le jeu de CA autorisées. Cela signifie que l’application DirectAPI doit contenir le certificat racine de CA utilisé pour émettre et signer le certificat du client.
Le jeu initial de CA autorisées est déterminé par Mastercard.
- Il vérifie si le certificat présenté correspond au statut du profil du commerçant. Un profil de production accepte uniquement les certificats de production, tandis qu'un profil de test accepte les certificats de test et de production.
Si les étapes 1 à 4 réussissent, l’authentification du commerçant est considérée comme réussie ; dans le cas contraire, la connexion est rejetée et un message d’erreur approprié est retourné.
- Si tous les contrôles indiqués dans les étapes 5 et 6 réussissent, le serveur accepte la connexion et permet à la demande d’opération de se poursuivre.
Vous pouvez choisir de présenter votre certificat client ou un autre certificat pour vous authentifier lorsque le payeur accède à votre application. Dans cette interaction, votre serveur Web agit comme serveur et le payeur comme client. L’intégration de ce mécanisme d’authentification peut apporter à vos payeurs l’assurance qu’ils effectuent une transaction avec une entreprise légitime.
Avant de passer en ligne avec votre certificat de production, vous pouvez développer et tester l'authentification PKI avec un certificat de test. Cela peut être utile, par exemple, lorsque vous ne souhaitez pas partager le certificat de production et la clé privée avec un intégrateur Web tiers.
Il est important que la certification que vous obtenez auprès de la CA que vous avez choisie réponde aux exigences de Mastercard en matière de mise en œuvre des certificats. Voici quelques points clés à prendre en compte lorsque vous obtenez votre certificat SSL.
- Le certificat doit être au format X.509.
- Le certificat doit comporter une extension Key-Usage, marquée comme critique, et comprendre l'authentification du client comme utilisation autorisée du certificat.
- Le certificat doit être émis par une CA approuvée par Mastercard. Contactez Mastercard pour obtenir une liste des CA approuvées.
- Le nom commun de sujet du certificat (CN) doit contenir le nom de domaine entièrement qualifié (avec ou sans caractère générique) du site Web pour lequel le certificat est acheté.
- Le champ Entreprise du sujet (O) doit contenir le nom de l'organisation du commerçant.
Après avoir obtenu le certificat auprès d'une CA de confiance, your payment service provider doit configurer votre certificat de test et/ou de production dans le Gestionnaire du commerçant dans le cadre de la configuration de tous les paramètres d'API pour votre profil de commerçant sur la passerelle. Si nécessaire, un certificat de commerçant peut être lié à plusieurs profils de commerçants de la même entreprise ou de plusieurs entreprises. Pour plus d’informations sur la manière de configurer les certificats de commerçant dans le Gestionnaire du commerçant, consultez la section Configuration de l'API dans le Guide de l’utilisateur du Gestionnaire du commerçant.
Le site contrôle la liste de certificats racines de CA acceptables utilisés pour vérifier les certificats de commerçant. Pour permettre la vérification du certificat, le système collecte la version codée en PEM du certificat de production via le Gestionnaire du commerçant. Il extrait le nom commun de sujet de ce certificat et le vérifie par rapport au nom commun de sujet du certificat présenté pendant la négociation SSL.
Après avoir configuré le certificat par rapport à votre profil de commerçant, vous devez suivre la procédure suivante pour l'installer dans votre environnement.
- Mettez la clé privée et le certificat à la disposition du logiciel client SSL qui établit la connexion SSL à Mastercard Gateway. Selon le logiciel, la clé privée, le certificat et la chaîne de certificats associée peuvent nécessiter une conversion dans un format pris en charge. Par exemple, les clés privées et les certificats sont souvent indiquées dans des fichiers texte, au format PEM, la clé privée étant protégée par un mot de passe. Dans Java, ces fichiers sont généralement chargés dans un magasin de clés Java. Veuillez consulter la documentation de votre logiciel pour les formats pris en charge.
Pour les environnements Java et .NET, nous vous recommandons de convertir les fichiers PEM en PKCS12.
- Dans la majorité des cas, la CA émettrice de votre certificat fournit également des certificats supplémentaires appelés chaînes de certificats. Vous devez les indiquer à Mastercard Gateway pendant la négociation SSL pour permettre à la passerelle de valider votre certificat. Votre logiciel client SSL comporte des instructions sur la manière de placer ces certificats et leur emplacement.
- Un test simple visant à vérifier si vous avez tous les certificats nécessaires consiste à les charger dans un navigateur Web tel qu'Internet Explorer, Firefox ou Safari, à accéder à l'URL Check Gateway de la passerelle DirectAPI et à récupérer le statut de la passerelle. Si les certificats sont correctement chargés, lors de l’accès à l’URL Check Gateway, le navigateur vous invitera à sélectionner/accepter le certificat à utiliser pour la connexion à la passerelle. Si le navigateur affiche cette invite et que la connexion réussit, vous obtiendrez la réponse suivante : {status: "OPERATING"}.
Référence de l'API Check Gateway URL (URL de vérification de la passerelle) [REST][NVP]
Vous souhaiterez peut-être passer d’un certificat existant à un nouveau certificat pour diverses raisons. Il peut s'agir, par exemple, de mettre à niveau un certificat en raison d'un changement de nom de société ou de passer d'un certificat de test à un certificat de production.
Pour passer à un nouveau certificat, your payment service provider doit ajouter le nouveau certificat en tant que certificat principal tandis que l'ancien certificat devient un certificat supplémentaire. Vous pouvez avoir un ou plusieurs certificats supplémentaires. Les commerçants qui sont configurés pour utiliser le nouveau certificat peuvent s'authentifier auprès de DirectAPI en utilisant l'ancien certificat ou le nouveau. Il s’agit d’une configuration intermédiaire jusqu’au moment où toutes les intégrations ont été mises à niveau pour utiliser le nouveau certificat. Pour plus d’informations sur l'ajout de certificats supplémentaires, consultez la section Configuration de l'API dans le Guide de l’utilisateur du Gestionnaire du commerçant.
Authentification de session
L'authentification de session utilise la session de paiement de la passerelle, qui constitue un conteneur temporaire pour les champs de la demande, pour authentifier le commerçant. La session de paiement étant créée par un commerçant authentifié (à l'aide d'une authentification par mot de passe/certificat), le payeur peut l'utiliser pour les interactions avec la passerelle, comme par exemple pour les opérations d'authentification.
Ce mécanisme d'authentification permet aux payeurs d'indiquer leurs informations de paiement directement à la passerelle. Les données du payeur sont obtenues via une interaction côté client avec la passerelle, via le navigateur du payeur ou via une application sur l'appareil mobile du payeur. Il propose un modèle d'intégration simple pour obtenir en toute sécurité les données de payeur requises, les demandes d'API à la passerelle étant effectuées directement depuis le client plutôt que depuis votre serveur.
Il utilise un mécanisme d’authentification HTTP de base (similaire à l’authentification par mot de passe) dans lequel vous devez indiquer « merchant.<votre ID de commerçant de la passerelle> » dans la partie userid et l’ID de session dans la partie password.
Pour utiliser ce type d'authentification :
- Créez une session en soumettant une demande d'API Create Session (Créer une session) de votre serveur au serveur de passerelle. Cette opération retourne un ID de session.
- Soumettez la demande Update Session (Mettre à jour la session) en utilisant l'authentification de session pour ajouter toutes les données pertinentes à la session créée à l'étape 1.
- Indiquez la session au payeur.
Transactions prises en charge
Les opérations suivantes prennent en charge l'authentification à l'aide d'un ID de session.
- Update Session (Mettre à jour la session)
- Initiate Authentication (Initier l'authentification)
- Authenticate Payer (Authentifier le payeur)
Champs d'entrée du payeur et de sortie du payeur
Dans les interactions authentifiées par session avec la passerelle, le payeur est limité à un sous-ensemble de champs dans une opération d'API. Ceux-ci sont appelés Champs d'entrée du payeur. Si vous indiquez des champs autres que les champs d'entrée du payeur dans une demande authentifiée par session, la demande est rejetée. Par exemple, le payeur ne peut pas soumettre de données telles que le montant de la commande.
Comme pour les champs d'entrée du payeur, la passerelle ne permet de retourner que certains champs en réponse à des interactions authentifiées par session avec la passerelle. Il s'agit des champs appelés champs de sortie du payeur. Seuls les champs devant être affichés à un payeur dans un navigateur ou une application pour exécuter une transaction sont retournés. Par exemple, les données de sécurité sensibles, telles que l'identifiant de session, ne sont pas retournées.
Update Session (Mettre à jour la session)
- billing.address.city
- billing.address.company
- billing.address.country
- billing.address.postcodeZip
- billing.address.stateProvince
- billing.address.stateProvinceCode
- billing.address.street
- billing.address.street2
- browserPayment.preferredLanguage
- correlationId
- customer.dateOfBirth
- customer.email
- customer.firstName
- customer.lastName
- customer.mobilePhone
- customer.nationalId
- customer.phone
- customer.taxRegistrationId
- device.browser
- device.browserDetails.3DSecureChallengeWindowSize
- device.browserDetails.acceptHeaders
- device.browserDetails.colorDepth
- device.browserDetails.javaEnabled
- device.browserDetails.language
- device.browserDetails.screenHeight
- device.browserDetails.screenWidth
- device.browserDetails.timeZone
- device.fingerprint
- device.hostname
- device.ipAddress
- device.mobilePhoneModel
- gatewayEntryPoint
- locale
- merchant
- order.id
- order.walletProvider
- session.version
- shipping.contact.email
- shipping.contact.firstName
- shipping.contact.lastName
- shipping.contact.mobilePhone
- shipping.contact.phone
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.expiry.month
- sourceOfFunds.provided.card.expiry.year
- sourceOfFunds.provided.card.mobileWallet.emv.emvData
- sourceOfFunds.provided.card.nameOnCard
- sourceOfFunds.provided.card.number
- sourceOfFunds.provided.card.provided.card.prefix
- sourceOfFunds.provided.card.securityCode
- sourceOfFunds.token
- sourceOfFunds.type
- transaction.acquirer.customData
- transaction.acquirer.traceId
- transaction.id
- correlationId
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.amount
- order.currency
- order.customerNote
- order.customerReference
- order.invoiceNumber
- result
- session.updateStatus
- session.version
Initiate Authentication (Initier l'authentification)
- apiOperation
- correlationId
- order.walletProvider
- session.id
- session.version
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.number
- sourceOfFunds.token
- sourceOfFunds.type
- authentication.3ds2.methodCompleted
- authentication.3ds2.methodSupported
- authentication.redirect.customized.3DS.methodPostData
- authentication.redirect.customized.3DS.methodUrl
- authentication.redirectHtml
- authentication.version
- correlationId
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.authenticationStatus
- order.currency
- order.status
- response.gatewayCode
- response.gatewayRecommendation
- result
- sourceOfFunds.provided.card.number
- sourceOfFunds.type
- transaction.authenticationStatus
- version
Authenticate Payer (Authentifier le payeur)
- apiOperation
- billing.address.city
- billing.address.company
- billing.address.country
- billing.address.postcodeZip
- billing.address.stateProvince
- billing.address.stateProvinceCode
- billing.address.street
- billing.address.street2
- correlationId
- device.browser
- device.browserDetails.3DSecureChallengeWindowSize
- device.browserDetails.acceptHeaders
- device.browserDetails.colorDepth
- device.browserDetails.javaEnabled
- device.browserDetails.language
- device.browserDetails.screenHeight
- device.browserDetails.screenWidth
- device.browserDetails.timeZone
- device.ipAddress
- order.walletProvider
- session.id
- session.version
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.expiry.month
- sourceOfFunds.provided.card.expiry.year
- sourceOfFunds.provided.card.number
- sourceOfFunds.provided.card.securityCode
- authentication.3ds2.acsReference
- authentication.3ds2.challenge.signedContent
- authentication.3ds2.methodCompleted
- authentication.3ds2.methodSupported
- authentication.3ds2.sdk.interface
- authentication.3ds2.sdk.timeout
- authentication.3ds2.sdk.uiType
- authentication.payerInteraction
- authentication.redirect.customized.3DS.acsUrl
- authentication.redirect.customized.3DS.cReq
- authentication.redirect.domainName
- authentication.redirectHtml
- authentication.version
- correlationId
- encryptedData.ciphertext
- encryptedData.nonce
- encryptedData.tag
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.authenticationStatus
- order.currency
- order.status
- response.gatewayCode
- response.gatewayRecommendation
- result
- sourceOfFunds.provided.card.number
- sourceOfFunds.type
- transaction.authenticationStatus
- version
Protection des informations du payeur avec SSL
Tous les sites Web qui collectent des informations sensibles ou confidentielles doivent protéger les informations transférées entre le navigateur Internet du payeur, l’application et Mastercard Gateway.
SSL est une technologie de sécurité qui sert à sécuriser les transactions entre le serveur Web et le navigateur Internet. Il s’agit de sécuriser toute information (telle que le numéro de carte de crédit du payeur) transmise par un navigateur Internet à un serveur Web (comme votre application d’achat). SSL empêche les données sur Internet d'être interceptées et visualisées par des destinataires indésirables.
Lorsque vous mettez en œuvre le modèle d’intégration Direct Payment, vous devez vous assurer que votre application présente un formulaire sécurisé utilisant SSL. Vous devez également envisager d’utiliser un formulaire sécurisé dans votre application lorsque vous collectez des informations confidentielles telles que les adresses des payeurs.
Comment mes payeurs peuvent-ils savoir si mon site utilise SSL ?
Lorsqu’un payeur se connecte à votre application avec SSL, il voit que http:// se transforme en https:// et qu’un petit cadenas doré apparaît dans son navigateur Internet, par exemple :
Chaque fois qu’un navigateur Internet se connecte à un serveur Web (site Web) par une connexion https://, cela signifie que la communication avec Mastercard Gateway est cryptée et sécurisée. Vous pouvez informer vos payeurs de ce fait, afin qu’ils sachent quoi rechercher lorsqu’ils effectuent des transactions sur votre site Web.
Tableau de référence des principales différences entre les modèles de sécurité
Le tableau suivant indique certaines différences clés entre les modèles d’authentification par mot de passe et par certificat dans le but de vous aider à choisir la solution d’authentification qui répond le mieux aux besoins de votre entreprise.
Authentification par mot de passe | Authentification par certificat | |
Quand l’utiliser |
Dans les petites entreprises où une authentification simple répond aux besoins. | Dans les grandes entreprises où le coût d’infrastructure lié à la mise en œuvre de PKI est minime par rapport aux gains en termes de sécurité associés à l’emploi d’un niveau d’authentification plus élevé. |
Compétences techniques requises |
Exige une connaissance de l’authentification HTTP de base | Exige une connaissance de l’authentification mutuelle et de la PKI faisant appel aux autorités de certification |
Facilité d’intégration |
Facile à intégrer | La configuration du fichier de magasin de clés et du reste de l’infrastructure peut rendre l’intégration plus complexe. |
Niveau d’authentification | Modéré | Élevé |
Coût | Méthode d’authentification la moins coûteuse à utiliser. | Implique des coûts supplémentaires, tels que le coût d’abonnement auprès de l’autorité de certification qui émet les certificats SSL. |
Avantages | Idéal pour les petits commerçants, pour lesquels le coût d'intégration est un facteur important et le modèle commercial n'exige pas un niveau de sécurité élevé. | L'authentification SSL mutuelle propose un très haut niveau de sécurité et est considérée comme une bonne pratique du secteur. Elle optimise les performances de l’authentification en utilisant la connexion SSL existante, qui est généralement créée quoi qu’il en soit. La surcharge liée à l’envoi du certificat client est minime. |
Inconvénients | Le mot de passe est intégré sous forme de texte clair dans l'en-tête d'authentification HTTP et doit exclusivement être envoyé sur SSL. Mastercard Gateway accepte uniquement les connexions sécurisées par SSL, protégeant ainsi le mot de passe contre toute divulgation ; toutefois, il est très important pour la sécurité de la connexion qu'une authentification appropriée des serveurs soit effectuée pour éviter toute divulgation accidentelle à des serveurs malveillants. | Aucun |
Prise en charge du partage d’informations d’identification entre plusieurs profils de commerçants | Impossible de partager les mots de passe entre plusieurs profils de commerçants | Vous permet de partager un ID de jeu de certificats avec plusieurs profils de commerçants au sein d’un prestataire de services de passerelle au commerçant ou sur plusieurs d’entre eux (basé sur les privilèges). |