- Directives d'intégration
- Mise en œuvre d'une intégration Hosted Session
Mise en œuvre dune intégration {0}
- Demander une interaction Hosted Session
- Méthodes de paiement prises en charge
- Gérer les réponses des rappels
- Écoute des événements sur les champs hébergés
- Style avancé pour les champs hébergés
- Configurer l'accessibilité des champs hébergés
- Accepter plusieurs cartes
- Champs de liste déroulante pour le mois et l'année d'expiration
- Test et passage en ligne
- Dépannage et questions fréquentes
Fonctionnalités Mastercard Gateway prises en charge
Sécurité des paiements et prévention des fraudes
- Mots de passe et certificats
- Authentification 3-D Secure EMV
- Gestion des risques
- Service de vérification d'adresse
- Jetons de cartes stockées de la passerelle
Opérations de paiement
Méthodes de paiement
Options de paiement
- Demande d'options de paiement
- Échéanciers de paiement
- Conversion de devise dynamique
- Paiements récurrents
- Paiements échelonnés
- Paiements non planifiés
Données supplémentaires
- Données de la compagnie aérienne
- Données Internet du client
- Données de commande et de poste
- Données personnalisées de l'acquéreur
- Données personnalisées du commerçant
- Reporting
Reporting
Autres fonctionnalités
Mise en œuvre d'une intégration Hosted Session
La bibliothèque client JavaScript Hosted Session vous permet de collecter les détails de paiement sensibles auprès du payeur dans les champs du formulaire de paiement, hébergés par Mastercard Gateway. La passerelle collecte les détails de paiement sensibles dans une session de paiement et les stocke temporairement en vue d'une utilisation ultérieure. Vous pouvez alors inclure une session de paiement à la place des détails de paiement dans la demande de transaction afin de traiter un paiement. Pour plus d'informations, voir Session de paiement.
Hosted Session est une méthode d'intégration conforme à la norme PCI v3 qui simplifie la conformité SAQ-A, tout en permettant de garder le contrôle sur la disposition et le style de la page de paiement. Dans ce modèle, l'intégralité des champs de paiement sensibles est intégrée aux iFrames provenant de et contrôlés par Mastercard Gateway. Les mécanismes de protection de sécurité des navigateurs standard isolent les champs sensibles, préservant ainsi l'intégrité du canal de paiement fourni par la passerelle.
Conditions préalables
- Vérifiez que votre profil de commerçant est activé pour le service Hosted Session.
- Hosted Session est uniquement pris en charge dans la version 18 et les versions ultérieures de DirectAPI.
Demander une interaction Hosted Session
Cette section décrit une intégration simple pour que Hosted Session collecte les détails de la carte de crédit d'un payeur.
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://ap-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <h3>Credit Card</h3> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="2" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="3" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="4" readonly></div> <div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay('card');">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } PaymentSession.configure({ session: "<your_session_ID>", fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD card: { number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year", nameOnCard: "#cardholder-name" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION if (response.status) { if ("ok" == response.status) { console.log("Session updated with data: " + response.session.id); //check if the security code was provided by the user if (response.sourceOfFunds.provided.card.securityCode) { console.log("Security code was provided."); } //check if the user entered a Mastercard credit card if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') { console.log("The user entered a Mastercard credit card.") } } else if ("fields_in_error" == response.status) { console.log("Session update failed with field errors."); if (response.errors.cardNumber) { console.log("Card number invalid or missing."); } if (response.errors.expiryYear) { console.log("Expiry year invalid or missing."); } if (response.errors.expiryMonth) { console.log("Expiry month invalid or missing."); } if (response.errors.securityCode) { console.log("Security code invalid."); } } else if ("request_timeout" == response.status) { console.log("Session update failed with request timeout: " + response.errors.message); } else if ("system_error" == response.status) { console.log("Session update failed with system error: " + response.errors.message); } } else { console.log("Session update failed: " + response); } } }, interaction: { displayControl: { formatCard: "EMBOSSED", invalidFieldCharacters: "REJECT" } } }); function pay() { // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS PaymentSession.updateSessionFromForm('card'); } </script> </body> </html>
Étape 1 : Créer une session
Créez une session en soumettant une demande Create Session
(Créer une session) à partir de votre application côté serveur. Veuillez spécifier une limite d'authentification de session de 25. La réponse retourne un ID de session que vous devez utiliser dans les étapes suivantes pour référencer cette session.
URL | https://ap-gateway.mastercard.com/api/rest/version/72/merchant/<your_gateway_merchant_ID>/session |
Méthode HTTP | POST |
{ "session":{ "authenticationLimit":25 } }
Étape 2 : Mettre de la session à jour avec le montant et la devise de la commande
Mettez à jour la session avec au moins la devise et le montant de la commande en soumettant une demande Update Session
(Mettre à jour la session) à partir de votre application côté serveur. Cette étape est requise pour demander ultérieurement si la carte est prise en charge et si le code de sécurité de la carte est requis.
URL | https://ap-gateway.mastercard.com/api/rest/version/72/merchant/<your_gateway_merchant_ID>/session/<your_session_ID> |
Méthode HTTP | PUT |
{ "order":{ "amount":100.00, "currency":"USD" } }
Étape 3 : Ajouter la bibliothèque JavaScript client session.js sur votre page de paiement
Incluez la bibliothèque JavaScript client session.js
hébergée par la passerelle sur votre page de paiement en ajoutant un élément script
dans l'élément head
. Le chemin vers ce fichier comporte la version de l'API et l'ID du commerçant pour la session. Cela place un objet PaymentSession
dans l'espace de noms de la fenêtre.
<script type="text/javascript" src="https://ap-gateway.mastercard.com/form/version/72/merchant/<your_gateway_merchant_ID>/session.js"></script>
Étape 4 : Créer le formulaire HTML pour la page de paiement comportant les champs de carte de crédit
readonly
et n'ont PAS l'attribut name
.Étape 5 : Appeler la fonction PaymentSession.configure(configuration)
L'objet configuration
vous permet de rattacher les champs hébergés à votre de page de paiement et/ou de configurer l'interaction de paiement. Vous devez indiquer les éléments suivants :
- Incluez le session.id créé dans l'étape 1 : Créer une session.
- Les sélecteurs de champ pour les champs de carte de crédit qui, lorsqu'ils sont indiqués, sont remplacés par les champs proxy correspondants intégrés dans les iFrames hébergés par Mastercard Gateway. les champs proxy ont le même aspect que les champs remplacés ; Vous pouvez collecter des détails d'autres types de paiements. Voir Méthodes de paiement prises en charge via Hosted Session.
-
La ou les options de limitation pour la prévention des détournements de clic
Le clickjacking, ou détournement de clic, se produit lorsqu'un attaquant piège un utilisateur pour qu'il clique sur un bouton ou un lien d'une autre page chargée derrière une ou plusieurs couches transparentes ou opaques, alors qu'il pense cliquer sur la page d'origine. Pour utiliser Hosted Session, vous devez implémenter une ou plusieurs des défenses suivantes contre les détournements de clic.
Option de limitation de cadre Implémentation javascript
incluez le JavaScript « frame-breaker » dans votre page de paiement. x-frame-options
Votre serveur doit retourner un en-tête de réponse HTTP X-Frame-Options. csp
Votre serveur doit retourner l'en-tête de réponse HTTP Content-Security-Policy comportant une directive « frame-ancestors ». Vous devez indiquer les défenses implémentées via le paramètre
frameEmbeddingMitigation
dans l'appelPaymentSession.configure(configuration)
. Pour plus d'informations sur les défenses en matière de détournement de clic, voir « Clickjacking Defense Cheat Sheet » sur le site Web externe OWASP. -
des rappels permettant de gérer les différents événements pendant l'interaction Hosted Session
initialized( )
: appelé lorsque les champs hébergés sont rattachés à votre page de paiement.formSessionUpdate( )
: appelé en réponse à la fonctionPaymentSession.updateSessionFromForm(paymentType)
(voir étape suivante)
Étape 6 : Appeler updateSessionFromForm
Appelez PaymentSession.updateSessionFromForm('card')
pour stocker les détails du paiement collectés pour le type de paiement 'card'
, dans une session de paiement. Lorsque l'opération est terminée, la fonction de rappel formSessionUpdate()
est appelée avec un paramètre de résultat. Vous devez vérifier la valeur de result.status
afin de déterminer si l'opération a réussi. Voir Gérer les réponses des rappels.
Étape 7 : Utiliser les données de session de paiement
Vous pouvez utiliser la session de paiement retourné (session.id) pour exécuter une création de jeton ou une transaction de paiement lorsque nécessaire. Pour plus d'informations, voir Exécution d'une opération au moyen de la session.
Méthodes de paiement prises en charge via Hosted Session
Hosted Session vous permet de configurer une ou plusieurs des méthodes de paiement suivantes pour collecter les détails du paiement du payeur. Les détails du paiement sont collectés via des champs hébergés joints à votre formulaire de paiement à l'exception des portefeuilles numériques où les détails du paiement sont collectés à partir d'une interaction avec le portefeuille.
Vous pouvez collecter les détails de carte suivants via des champs hébergés :
card.number
card.expiryMonth
card.expiryYear
card.securityCode
card.nameOnCard
card.expiryMonth
est configuré, card.expiryYear
est obligatoire, et vice versa.Vous pouvez collecter les détails de cartes-cadeaux suivants via des champs hébergés :
giftCard.number
giftCard.pin
Hosted Session vous permet de collecter les détails des paiements Direct Payment (paiements) et des dépôts Direct Deposit (remboursements) via Automated Clearing House. Vous pouvez collecter les détails Automated Clearing House suivants via des champs hébergés :
ach.routingNumber
ach.bankAccountNumber
ach.bankAccountNumberConfirmation
ach.bankAccountHolder
ach.accountType
Voir Intégration Automated Clearing House via Hosted Session.
Hosted Session vous permet de collecter les détails du paiement à partir de l'interaction avec le portefeuille. Actuellement, les interactions de portefeuille SRC (Secure Remote Commerce) sont prises en charge. L'option SRC (Secure Remote Commerce) doit être activée via Mastercard Gateway pour pouvoir initier cette interaction. Voir SRC (Secure Remote Commerce).
Commentaires sur la validation des données de champ
Hosted Session vous permet d'indiquer un commentaire de validation au payeur lors des différentes étapes d'interaction de paiement sur l'interface utilisateur :
- Sur chaque frappe en écoutant le rappel
onValidityChange
:
PaymentSession.onValidityChange(["card.number", "card.nameOnCard"], function (selector, result) { if (result.isValid) { console.log("The field value is valid"); document.querySelector(selector).style.borderColor = "green"; } else if (result.isIncomplete) { console.log("The field value is not yet valid"); document.querySelector(selector).style.borderColor = "grey"; } else { console.log("The field value is invalid"); document.querySelector(selector).style.borderColor = "red"; } });
- Lorsque le payeur a terminé la saisie et quitte le champ :
- Écoute de l'événement
onBlur()
- Appel de
validate()
- Affichage de toutes les erreurs pour ce champ à partir du rappel
validate()
PaymentSession.onBlur( ["card.number", "card.nameOnCard", "card.securityCode", "card.expiryYear", "card.expiryMonth"], function (selector, role) { PaymentSession.validate('card', function (allresult) { if (allresult.card[role].isValid) { console.log("The field is valid"); document.querySelector(selector).style.borderColor = "green"; } else { console.log("The field is invalid"); document.querySelector(selector).style.borderColor = "red"; } }); });
- Écoute de l'événement
- Lorsque le payeur clique sur le bouton d'action suivante de la page :
- Appel de
updateSessionFromForm()
- Affichage de toutes les erreurs du rappel
formSessionUpdate
- Appel de
Quelle que soit votre approche, vous devez prévoir et gérer les erreurs du rappel formSessionUpdate
. La méthode validate()
peut indiquer la validité, mais la validation formSessionUpdate
est plus complète et peut détecter des erreurs supplémentaires.
Gérer les réponses des rappels
initialized(result)
result.status=="ok"
Les champs hébergés ont été rattachés avec succès à votre page de paiement.
// An ok response { "status":"ok", }
result.status=="system_error"
ou result.status=="request_timeout"
Une erreur s'est produite lors du rattachement des champs hébergés. Vous devez réessayer après quelques instants.
// An error response (system_error) { "status": "system_error", "message": "System error message." } // An error response (request_timeout) { "status" : "request_timeout", "message": "Request timeout error message." }
formSessionUpdate(result)
result.status=="ok"
La session contient désormais les détails de la carte collectés.
// An ok response { "status":"ok", "merchant": "TESTMERCHANT", "session": { "id": "SESSION000218450948092491657986" "updateStatus":"SUCCESS", "version":"e3f144ce02" }, "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "nameOnCard": "John Smith", "number": "512345xxxxxx8769", "scheme": "MASTERCARD" } }, "type": "CARD" }, "version": "43" }
result.status=="fields_in_error"
Les données saisies par le payeur ne sont pas valides et vous devez l'inviter à les mettre à jour. La structure de la réponse errors
(Erreurs) comporte les informations sur les champs non valides.
// An error response (fields_in_error) { "status": "fields_in_error", "session": { "id": "SESSION000218450948092491657986" }, "errors": { "cardNumber": "invalid", "securityCode": "invalid" }, version: "43" }
result.status=="system_error"
ou result.status=="request_timeout"
Une erreur s'est produite lors du traitement de la mise à jour. Vous devez réessayer la mise à jour de la session après quelques instants.
// An error response (system_error) { "status": "system_error", "session": { "id": "SESSION000218450948092491657986" }, "errors": { "message": "System error message." }, "version": "43" } // An error response (request_timeout) { "status" : "request_timeout", "session": { "id": "SESSION000218450948092491657986" }, "errors": { "message": "Request timeout error message." }, "version": "43" }
Écoute des événements sur les champs hébergés
Hosted Session vous permet d'enregistrer les fonctions de rappel afin de gérer les événements survenant sur les champs hébergés lors de l'interaction du payeur.
onChange( )
: appelé lorsque la valeur saisie dans le champ hébergé dans l'iFrame a été modifiée.onFocus( )
: appelé lorsque le champ hébergé dans l'iFrame est mis en surbrillance.onBlur( )
: appelé lorsque le champ hébergé dans l'iFrame n'est plus en surbrillance.onMouseOver( )
: appelé lorsque la souris est passée sur le champ hébergé.onMouseOut( )
: appelé lorsque la souris est retirée du champ hébergé.
/** * Provide an array of field roles for proxy fields as the first parameter * Each callback function is invoked with the selector for the field whose proxy triggered the event. */ PaymentSession.onBlur(['card.number'], function(selector) { //handle blur event }); PaymentSession.onFocus(['card.number', 'card.securityCode'], function(selector) { //handle focus event }); PaymentSession.onChange(['card.securityCode'], function(selector) { //handle change event }); PaymentSession.onMouseOver(['card.number'], function(selector) { //handle mouse over event }); PaymentSession.onMouseOut(['card.number'], function(selector) { //handle mouse out event });
Style avancé des champs hébergés
Hosted Session vous permet de définir le style des champs hébergés conformément à l'aspect des champs remplacés sur votre de page de paiement.
setFocus( )
: met le champ hébergé spécifié en surbrillance.setFocusStyle( )
: définit les attributs de style pour les champs hébergés spécifiés lorsqu'ils sont mis en surbrillance.setHoverStyle( )
: définit les attributs de style pour les champs hébergés spécifiés lorsque la souris passe dessus.setPlaceholderStyle( )
: définit les attributs de style pour le texte des espaces réservés pour les champs hébergés spécifiés.setPlaceholderShownStyle( )
: définit les attributs de style pour les champs hébergés spécifiés lorsque le texte des espaces réservés est visible.
PaymentSession.setFocus('card.number'); PaymentSession.setFocusStyle(["card.number","card.securityCode"], { borderColor: 'red', borderWidth: '3px' }); PaymentSession.setHoverStyle(["card.number","card.securityCode"], { borderColor: 'red', borderWidth: '3px' }); PaymentSession.setPlaceholderStyle(["card.number", "card.nameOnCard"], { color: 'blue', fontWeight: 'bold', textDecoration: 'underline' }); PaymentSession.setPlaceholderShownStyle(["card.number", "card.nameOnCard"], { color: 'green', fontWeight: 'bold', textDecoration: 'underline' });
Champs de liste déroulante pour le mois et l'année d'expiration
Hosted Session vous permet d'utiliser des valeurs de listes déroulantes pour le mois et l'année d'expiration. Voir l'exemple de code ci-dessous pour plus de détails.
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://ap-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div> <div>Expiry Month: <select id="expiry-month" class="form-control input-md" required="" readonly> <option value="">Select Month</option> <option value="01">January</option> <option value="02">February</option> <option value="03">March</option> <option value="04">April</option> <option value="05">May</option> <option value="06">June</option> <option value="07">July</option> <option value="08">August</option> <option value="09">September</option> <option value="10">October</option> <option value="11">November</option> <option value="12">December</option> </select> </div> <div>Expiry Year: <select id="expiry-year" class="form-control input-md" required="" readonly> <option value="">Select Year</option> <option>21</option> <option>22</option> <option>23</option> <option>24</option> <option>25</option> <option>26</option> <option>27</option> <option>28</option> <option>29</option> <option>30</option> <option>31</option> <option>32</option> <option>33</option> <option>34</option> <option>35</option> <option>36</option> <option>37</option> <option>38</option> <option>39</option> </select> </div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="4" readonly></div> <div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="3" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } var sessions = []; PaymentSession.configure({ fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD card: { number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year", nameOnCard: "#cardholder-name" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION if (response.status) { if ("ok" == response.status) { console.log("Session updated with data: " + response.session.id); //check if the security code was provided by the user if (response.sourceOfFunds.provided.card.securityCode) { console.log("Security code was provided."); } //check if the user entered a Mastercard credit card if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') { console.log("The user entered a Mastercard credit card.") } } else if ("fields_in_error" == response.status) { console.log("Session update failed with field errors."); if (response.errors.cardNumber) { console.log("Card number invalid or missing."); } if (response.errors.expiryYear) { console.log("Expiry year invalid or missing."); } if (response.errors.expiryMonth) { console.log("Expiry month invalid or missing."); } if (response.errors.securityCode) { console.log("Security code invalid."); } } else if ("request_timeout" == response.status) { console.log("Session update failed with request timeout: " + response.errors.message); } else if ("system_error" == response.status) { console.log("Session update failed with system error: " + response.errors.message); } } else { console.log("Session update failed: " + response); } } }, interaction: { displayControl: { formatCard: "EMBOSSED", invalidFieldCharacters: "REJECT" } } }); function pay() { // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS PaymentSession.updateSessionFromForm('card'); } </script> </body> </html>
Configurer l'accessibilité des champs hébergés
Hosted Session propose des fonctionnalités qui peuvent améliorer l'accessibilité de votre site web.
<!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Cardholder Name: <input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="1" readonly></div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="2" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="3" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="4" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="card security code" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div>
Les options suivantes vous permettent de mieux contrôler l'expérience utilisateur des payeurs avec des besoins d'accessibilité :
Définir le titre de l'iFrame
L'attribut Titre de l'iFrame du champ hébergé peut être contrôlé à l'aide d'un attribut Titre sur le champ.
Définir les attributs ARIA (Accessibility Rich Internet Applications)
Hosted Session prend en charge les attributs ARIA, que vous pouvez utiliser pour améliorer l'expérience des payeurs utilisant des technologies d'assistance.
Définir le paramètre d'affichage de caractère non valide
Pour une meilleure expérience pour les utilisateurs utilisant une technologie d'assistance, envisagez d'accepter tous les caractères dans les champs hébergés. Pour ce faire, définissez le paramètre d'affichage interaction.displayControl.invalidFieldCharacters=ALLOW
dans la méthode PaymentSession.configure()
.
Définir l'attribut lang
Ajoutez l'attribut lang à l'élément html.
<html lang="en"> <head></head> <body></body> </html>
Étiquette masquée et message d'erreur
Tous les champs hébergés contiennent une étiquette masquée et les champs hébergés obligatoires contiennent un message d'erreur masqué. Toutes les erreurs résultant de l'appel PaymentSession.updateSessionFromForm()
déclencheront des étiquettes de message d'erreur. Vous pouvez en outre déclencher vos propres erreurs en utilisant la méthode PaymentSession.setMessage()
.
Par exemple, l'étiquette masquée du champ du numéro de carte est « Numéro de carte ». Le message d'erreur masqué pour le numéro de carte manquant est « Le numéro de carte est manquant, veuillez saisir la valeur ». Le message d'erreur masqué pour un numéro de carte non valide est « Le numéro de carte n'est pas valide, veuillez saisir la valeur correcte ». Lors du déplacement entre les champs hébergés à l'aide de la tabulation, seule l'étiquette masquée et le message d'erreur masqué, et non l'étiquette réelle ou le message réels affichés dans l'IU, sont lus par le lecteur d'écran.
Définir la propriété de paramètre régional dans l'objet de configuration
La propriété de paramètre régional propose des traductions pour tous les champs hébergés, y compris les étiquettes et les messages d'erreur masqués. Si cette propriété n'est pas définie, la valeur par défaut est l'anglais. Les valeurs prises en charge pour cette propriété sont les suivantes : de_DE, el_GR, en_US, es_MX, es_ES, fr_CA, fr_FR, it_IT, ja_JA, pl_PL, pt_BR, ro_RO, zh_CN.
Pour éviter de confondre les payeurs, il est recommandé que l'attribut lang corresponde à la propriété de paramètre régional.
PaymentSession.configure({ fields: { card: { nameOnCard: cardHolderNameField ? "#card-holder-name" : null, number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year" } }, frameEmbeddingMitigation: ["javascript"], locale:"fr", callbacks: { } });
Mise au point automatique
L'une des fonctionnalités HTML5 par défaut ne fonctionne pas avec les champs hébergés, c'est-à-dire que lorsque le payeur clique sur l'étiquette, aucune mise au point automatique n'est effectuée sur l'élément d'entrée/de sélection correspondant. Pour ce faire, vous devez utiliser setFocus
.
Accepter plusieurs cartes via Hosted Session
Hosted Session vous permet d'accepter plusieurs cartes de votre payeur sur la même page. Dans ce cas, chaque carte devient une session de paiement séparée et une commande séparée (lorsque vous utilisez la session de paiement dans une transaction de paiement). Cela peut être très utile lorsqu'un client, par exemple, souhaite pouvoir payer avec plusieurs cartes pour la même réservation. Votre site Web doit alors pouvoir assembler ces commandes générées à partir de sessions de paiement séparées en une réservation unique pour le client.
Demander une interaction Hosted Session multiple
Pour accepter plusieurs cartes, vous devez appeler la fonction PaymentSession.configure()
avec le paramètre scope
. Ce paramètre peut être une chaîne unique utilisée pour identifier un bloc de données de paiement par carte et n'a pas besoin de référencer un HTML spécifique sur la page. Les données que vous stockez sur votre serveur de commerçant pour chaque carte doivent être conservées dans un cadre séparé.
PaymentSession.configure('configuration', scope)
Le paramètre scope
sur les appels Hosted Session suivants devient obligatoire si l'appel PaymentSession.configure()
initial est effectué avec scope
.
PaymentSession.updateSessionFromForm('card', 'card-type', scope)
PaymentSession.setFocus('cardNumber', scope)
Le paramètre scope
est facultatif sur les appels suivants si une interaction est configurée avec un cadre. Si aucun paramètre « scope » n'est spécifié dans les appels, la fonction/le rappel s'applique à tous les jeux de données de carte dans l'iFrame hébergé.
PaymentSession.setFocusStyle([<HostedFieldsRole>], styles, scope)
PaymentSession.setHoverStyle([<HostedFieldsRole>], styles, scope)
PaymentSession.onFocus([<HostedFieldsRole>],function(selector), scope)
PaymentSession.onBlur([<HostedFieldsRole>], function(selector), scope)
PaymentSession.onChange([<HostedFieldsRole>], function(selector), scope)
PaymentSession.onMouseOver([<HostedFieldsRole>], function(selector), scope)
PaymentSession.onMouseOut([<HostedFieldsRole>], function(selector), scope)
Exemple
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://ap-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Cardholder Name: <input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="1" readonly></div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="2" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="3" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="4" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } var sessions = []; PaymentSession.configure({ fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD card: { number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year", nameOnCard: "#cardholder-name" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION AS PER USUAL MANNER. if (response.status) { if ("ok" == response.status) { // RECORD THE SESSIONID RETURNED AND ASSOCIATE IT WITH THE SCOPE CONFIGURED. sessions.push(JSON.parse('{ "scopeId": "' + response.scopeId + '", "sessionId": "' + response.session.id + '"}')); } } else { console.log("Session update failed: " + response); } } }, interaction: { displayControl: { formatCard: "EMBOSSED", invalidFieldCharacters: "REJECT" } } }, 'card-payment-details-#1'); // ADD ANY UNIQUE STRING IDENTIFIER VALUE TO THE CONFIGURE CALL function pay() { sessions.forEach(function (e) { // UPDATE THE SESSION WITH THE FIELD VALUES. THE SCOPE MUST BE THE THIRD PARAMETER. PaymentSession.updateSessionFromForm('card', undefined, e.scopeId); }); } </script> </body> </html>
Test de votre intégration
Avant de la mettre en ligne, vous devez tester votre intégration pour vous assurer qu'elle fonctionne correctement.
Pour prendre en charge une connexion supplémentaire lors du test de votre intégration Hosted Session (en utilisant un ID de commerçant TEST), ajoutez ?debug=true
à l'URL.
https://ap-gateway.mastercard.com/form/version/72/merchant/<TESTMERCHANTID>/session.js?debug=true
Dépannage et questions fréquentes
Pour gérer cet événement, vérifiez les informations du type de carte (sourceOfFunds.provided.card.brand
et sourceOfFunds.provided.card.scheme
) dans la réponse PaymentSession.updateSessionFromForm('card')
, validez-les par rapport à la liste des types de carte que vous prenez en charge et affichez un message d'erreur si le type de carte n'est pas accepté.
Si le payeur n'indique pas de code CSC/CVV, le champ securityCode
n'est PAS retourné dans la réponse PaymentSession.updateSessionFromForm('card')
. Si vous exigez la saisie d'un code CSC/CVV et qu'aucune valeur n'est indiquée, vous devez afficher une erreur au payeur.
Il y a des problèmes connus avec les rappels d'événement sur les systèmes d'exploitation et les navigateurs suivants :
- Internet Explorer 11 sur Windows 10 : si
interaction.displayControl.formatCard=EMBOSSED
, l'événementonChange
n'est pas déclenché lorsque vous modifiez la valeur d'un champ hébergé. - iOS9 sur iPhone 6+ : les événements
onChange( )
etonBlur( )
ne sont pas déclenchés lorsque le payeur saisit des données dans un champ hébergé et touche un autre champ sur la page de paiement. En outre, le payeur ne peut pas naviguer entre les champs hébergés et les autres champs sur la page de paiement.
À compter de la version 51 de l'API, vous pouvez collecter les détails de paiement à partir d'une ou de plusieurs cartes dans une interaction Hosted Session. Cela permet au payeur d'utiliser plusieurs cartes de crédit pour payer une réservation unique ; cependant, les détails de paiement de chaque carte générant une commande séparée, il est de votre responsabilité d'assembler ces commandes séparées en une seule et même réservation pour le payeur.
Un identifiant de session unique est créé pour chaque carte, que vous devez stocker sur votre serveur Web. Au cours de l'interaction, le payeur peut choisir de retirer une carte et cette action supprime de votre serveur Web les données de session associées à la carte.
Le modèle POST Hosted Payment Session est rendu obsolète par l'intégration Hosted Session JavaScript (session.js).
Pour les intégrations POST Hosted Payment Session existantes, voir les directives d'intégration et la référence de l'API.
Le modèle JavaScript HPF.js Hosted Payment Session est rendu obsolète par l'intégration Hosted Session JavaScript (session.js).
Pour les intégrations HPF.js Hosted Payment Session existantes, voir les directives d'intégration et la référence de l'API.