Effectuer un paiement
Cette rubrique décrit les étapes que vous devez suivre pour effectuer un paiement à l'aide d'une session dans laquelle vous recueillez des données de paiement sensibles auprès du payeur avec des champs hébergés sur votre page de paiement. Cela est accompli à l'aide de la Session JavaScript library(session.js) en plus de WSAPI. Pour un exemple complet d'extrait de code de l'implémentation complète d'une page de paiement sur un site Web, voir Exemple de code de page de paiement.
Étape 1 : Créer une session
Créez une session en soumettant une demandeCreate Session (Créer une session) depuis votre serveur. Spécifiez une limite d'authentification de session de 25. La réponse renvoie un ID de session que vous devez utiliser dans les étapes suivantes pour référencer cette session.
| URL | https://na-gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/session |
| Méthode HTTP | POST |
{
"session": {
"authenticationLimit": 25
}
}
Étape 2 : Mettre à jour la session avec les détails 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) depuis votre serveur. La devise de la commande est nécessaire pour que vous puissiez déterminer si la carte de crédit que le payeur souhaite utiliser est prise en charge et s'il doit fournir son cryptogramme visuel (CSC).
| URL | https://na-gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/session/<session_ID> |
| Méthode HTTP | PUT |
{
"order": {
"amount": 100,
"currency": "USD"
}
}
Étape 3 : Inclure la bibliothèque Session JavaScript
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.
<html> <head> <script src="https://na-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> </head> </html>
Étape 4 : Créer la page de paiement
Créez le code HTML de votre page de paiement, y compris les champs permettant de recueillir les informations de paiement nécessaires auprès du payeur.
readonly ne comportent pas l'attribut name .Vous pouvez utiliser un ou plusieurs des modes de paiement suivants pour collecter les détails de paiement du payeur. Les champs que vous devez inclure sur votre page de paiement dépendent du mode de paiement :
Cartes de crédit et de débit
Vous pouvez collecter les détails de carte suivants dans les champs hébergés :
card.numbercard.expiryMonthcard.expiryYearcard.securityCodecard.nameOnCard
card.expiryMonth est utilisé, card.expiryYear est obligatoire, et vice versa.Cartes-cadeaux
Vous pouvez collecter les détails de cartes-cadeaux suivants dans des champs hébergés :
giftCard.numbergiftCard.pin
Pour plus d'informations, voir Cartes-cadeaux.
Automated Clearing House Paiements (ACH)
Vous pouvez collecter les détails des paiements directs (paiements) et des dépôts (remboursements) via Automated Clearing House. Vous pouvez collecter les détails Automated Clearing House suivants dans des champs hébergés :
ach.routingNumberach.bankAccountNumberach.bankAccountNumberConfirmationach.bankAccountHolderach.accountType
Pour plus d'informations, voir Automated Clearing House.
Click to Pay
Vous pouvez collecter les détails de paiement à partir de l'interaction Click to Pay. Pour plus d'informations, voir l'intégration Click to Pay Hosted Session.
L'exemple de code suivant illustre les champs de page de paiement nécessaires pour un paiement par carte de crédit.
<!-- 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>
Étape 5 : Configurer la session
Appelez la fonction PaymentSession.configure() avec un objet de configuration comme argument pour rattacher les champs hébergés à votre page de paiement et configurer l'interaction de paiement. Vous devez fournir les éléments suivants dans l'objet de configuration :
- ID de session reçu lorsque vous avez créé la session.
- Sélecteurs de champ pour les champs hébergés pour des modes de paiement spécifiques. La configuration les remplace 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.
- 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 mettre en œuvre une ou plusieurs des défenses suivantes contre les attaques par détournement de clics et spécifier lesquelles à l'aide du champ frameEmbeddingMitigation :
- Javascript : incluez le JavaScript « frame-breaker » sur votre page de paiement.
- x-frame-options : votre serveur renvoie un en-tête de réponse HTTP X-Frame Options.
- csp : votre serveur renvoie un en-tête de réponse HTTP Content-Security-Policy comportant une directive frame-ancestors.
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.
- Rappels permettant de gérer les différents événements pendant l'interaction Hosted Session :
- initialized() est appelé lorsque les champs hébergés sont rattachés à votre page de paiement.
- formSessionUpdate() est appelé en réponse à la fonction PaymentSession.updateSessionFromForm(paymentType) (voir l'étape suivante).
- Détails d'interaction qui définissent les options de visibilité et d'interaction du payeur pour certaines informations affichées.
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
},
},
interaction: {
displayControl: {
formatCard: “EMBOSSED”,
invalidFieldCharacters: “REJECT”
}
}
});
Étape 6 : Mettre à jour la session avec les détails des champs
Une fois que le payeur a saisi les détails de son paiement dans les champs hébergés, appelez la fonction PaymentSession.updateSessionFromForm() avec le mode de paiement applicable comme argument. La fonction stocke les détails de paiement collectés dans la session de paiement. Lorsque l'opération est terminée, le rappel formSessionUpdate() est appelé avec un paramètre de résultat. Vérifiez le champ result.status pour déterminer si l'opération a réussi. Pour plus d'informations, voir Gestion des réponses de rappel.
function pay() {
// UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
PaymentSession.updateSessionFromForm('card');
}
Étape 7 : Créer un paiement à l'aide de la session
Envoyez la transaction de paiement (ou autre opération connexe) depuis votre serveur vers la passerelle en utilisant l'ID de session (session.id) dans la demande :
- Envoyez la demande Retrieve Session (Extraire la session) pour vérifier les détails inclus dans la session.
- Créez la demande de transaction en ajoutant tous les champs nécessaires non inclus dans la session.
- Envoyez la demande de transaction.
Vous pouvez envoyer plusieurs opérations liées au paiement en utilisant la même session. Par exemple, vous pouvez à la fois lancer un paiement avec une opération PAY (Payer) et stocker un jeton représentant les détails du paiement (pour une utilisation dans des transactions futures) avec l'opération Create or Update Token (Créer ou mettre à jour un jeton).
Exemple de code de page de paiement
L'exemple de code suivant illustre le code HTML pour une page de paiement complète.
<html>
<head>
// INCLUDE SESSION.JS JAVASCRIPT LIBRARY
<script src="https://na-gateway.mastercard.com/form/version/<version>/merchant/<merchant_ID>/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>
Rappels de la page de paiement
Hosted Session vous permet d'utiliser différents rappels pour personnaliser le comportement de la page de paiement et le type de commentaires qu'elle fournit au payeur.
Rappels pour la configuration de session
Cette rubrique définit les rappels de configuration de session et les réponses retournées par leurs rappels de résultats. Pour un exemple de gestion des rappels dans le code de votre page de paiement, voir Exemple de code de page de paiement.
Les rappels utilisés dans la fonction PaymentSession.configure() :
- Le rappel initialized(result) est appelé lorsque les champs hébergés sont rattachés à la page de paiement :
- Si result.status=="ok", les champs hébergés sont correctement rattachés à votre page de paiement.
- Si result.status=="system_error" ou result.status=="request_timeout", une erreur s'est produite lors du rattachement des champs hébergés. Réessayez après un court délai.
Exemple de réponse d'initialisation réussie// An ok response { "status":"ok", }Exemple de réponse d'échec d'initialisation// 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." } - Le rappel formSessionUpdate(result) est appelé lorsque le contenu du champ hébergé est stocké dans la session :
- Si result.status=="ok", la session contient désormais les détails de paiement collectés.
Exemple de mise à jour de session de formulaire pour une réponse réussie// 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" } - Si result.status=="fields_in_error", la saisie du payeur n'est pas valide. Invitez le payeur à mettre à jour ses informations. La structure de la réponse errors comporte les informations sur les champs non valides.
- Si result.status=="system_error" ou result.status=="request_timeout", une erreur s'est produite lors du traitement de la mise à jour. Réessayez la mise à jour de session après un court délai.
// An error response (fields_in_error)
{
"status": "fields_in_error",
"session": {
"id": "SESSION000218450948092491657986"
},
"errors": {
"cardNumber": "invalid",
"securityCode": "invalid"
},
version: "43"
}
// 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"
}
Rappels pour 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. Les événements vous permettent de suivre ce que fait le payeur et de lui fournir des commentaires de validation au cours des différentes étapes de l'interaction de paiement.
Vous pouvez enregistrer les fonctions de rappel pour les événements suivants :
- 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. Lorsque le payeur a terminé la saisie et quitte le champ et que cet événement est déclenché, appelez la fonction validate() et affichez toutes les erreurs pour le champ à partir du rappel de la fonction validate().
- 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é.
- onValidityChange() : après chaque frappe du payeur sur le clavier, fournit un retour d'information sur la validité des données saisies par le payeur jusqu'à présent.
/**
* 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", "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";
}
});
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
});
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";
}
});
Questions fréquentes
Comment puis-je gérer l'événement lorsqu'un type de carte saisi par le payeur n'est pas pris en charge par mon profil de commerçant ?
Pour gérer cet événement, utilisez d'abord l'opération PAYMENT OPTIONS INQUIRY (Demande d'options de paiement) pour obtenir une liste des types de carte pris en charge. Consultez ensuite les informations sur le type de carte (sourceOfFunds.provided.card.brand and sourceOfFunds.provided.card.scheme) dans la réponse PaymentSession.updateSessionFromForm('card'), validez-les par rapport à la liste des types de cartes pris en charge et affichez un message d'erreur si le type de carte n'est pas accepté.
Comment savoir si le cryptogramme visuel ou le CVV du payeur est requis et a été fourni ?
Pour savoir si le cryptogramme visuel ou le CVV est requis, utilisez l'opération PAYMENT OPTIONS INQUIRY (Demande d'options de paiement). Si le payeur ne fournit pas de cryptogramme visuel/CVV, le champ securityCode n'est PAS retourné dans la réponse PaymentSession.updateSessionFromForm('card'). Si vous exigez la saisie d'un cryptogramme visuel/CVV et qu'aucune valeur n'est indiquée, vous devez afficher une erreur au payeur.
Les rappels d'événement pour les champs hébergés fonctionnent-ils sur tous les navigateurs ?
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énement onChange() n'est pas déclenché lorsque vous modifiez la valeur d'un champ hébergé.
- iOS9 sur iPhone 6+ : les événements onChange() et onBlur() 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.