- Directives d'intégration
- Mise en œuvre d'une intégration Hosted Payment Session
- Hosted Payment Session avec modèle JavaScript
- Génération de votre intégration
Génération de votre intégration
Cette page fournit des instructions pour effectuer l'intégration avec Hosted Payment Session et le modèle JavaScript (HPF.js). La création et la soumission de la page de paiement sont des étapes essentielles de l'intégration du commerçant pour ce modèle. Les détails de la carte collectés auprès du payeur sont soumis directement à Mastercard Gateway au moyen d'une méthode JavaScript. Mastercard Gateway stocke les détails de la carte dans un identificateur de session qui vous est renvoyé une fois toutes les erreurs résolues. Vous pouvez utiliser l'identificateur de session au lieu des détails de la carte pour lancer une transaction de paiement.
Incluez la bibliothèque JavaScript (hpf.js) Hosted Payment Session dans la page de paiement et configurez l'ID du commerçant.
<script id="hpfScript" src="https://na-gateway.mastercard.com/form/v3/hpf.js"></script> <script>HostedForm.setMerchant(<my merchantId>);</script>
<my merchantId> par votre ID de commerçant fourni par Mastercard Gateway. Pour tester votre intégration en tant que commerçant de test, faites précéder votre ID de commerçant de « TEST ». Par exemple, TESTMERCHANT123, où l'ID de commerçant est « MERCHANT123 ».Vous devez collecter les détails de la carte (numéro de carte, code sécurité, mois d'expiration et année d'expiration) auprès du payeur et les transférer dans la méthode HostedForm.createSession( )/HostedForm.updateSession( ). Un exemple de formulaire HTML qui collecte tous les détails de la carte est fourni ci-dessous.
<!-- REPLACE THE action URL with the payment URL on your webserver --> <form name="myform" method="POST" action="https://my.company.com/pay">
<!-- Name attributes are not provided for the card details to stop them from being submitted to your web server as part of the form submission --> Carte : <input type="text" id="cardNumber"> CSC : <input type="text" id="cardSecurityCode"> Mois : <input type="text" id="expiryMonth"> Année : <input type="text" id="expiryYear">
<!-- Other fields can be added to enable you to collect additional data on the payment page --> E-mail : <input type="text" name="email">
<!-- The hidden values below can be set in the updateSessionCallback function as they are returned when creating the session --> <input type="hidden" name="sessionId" id="sessionId"> <input type="hidden" name="cardBrand" id="cardBrand"> <input type="button" value="Pay" onclick="doCheckout()"> </form>
"https://my.company.com/pay" par l'URL de votre serveur Web hébergeant une page qui gérera le traitement du paiement après la création d'un identificateur de session.Les méthodes suivantes proposées dans la bibliothèque HPF.js permettent de créer et/ou de mettre à jour une session et sont appelées lors de la soumission des détails de la carte.
Création d'une session
Vous pouvez créer une session au moyen de la méthode HostedForm.createSession( ) qui admet comme paramètres les détails de carte collectés auprès du payeur et une fonction de rappel.
HostedForm.createSession(sessionDetails, createSessionCallback);
Vous pouvez également créer une session en appelant la méthode HostedForm.updateSession( ) sans transmettre d'identificateur de session.
HostedForm.updateSession(sessionDetails, updateSessionCallback);
Voici un exemple de code qui montre comment appeler la méthode HostedForm.createSession() ou HostedForm.updateSession() pour créer une session.
// Collect the card details based on the 'id' of the form elements
var getSessionDetailsFromForm = function() {
return {
cardNumber: document.getElementById('cardNumber').value,
cardSecurityCode: document.getElementById('cardSecurityCode').value,
cardExpiryMonth: document.getElementById('expiryMonth').value,
cardExpiryYear: document.getElementById('expiryYear').value
}
}
// Call doCheckout() from the form submit onClick() event
var doCheckout = function() {
var sessionDetails = getSessionDetailsFromForm();
HostedForm.createSession(sessionDetails, callback);
// HostedForm.updateSession(sessionDetails, callback);
};
Mise à jour d'une session
Si vous appelez la méthode HostedForm.updateSession( ) en transmettant un identificateur de session, les détails de la session sont mis à jour, le cas échéant. Cela est utile si vous disposez déjà d'une session contenant des détails comme l'adresse de facturation et d'expédition, mais que vous souhaitez ajouter ultérieurement les détails du paiement à la session dans le flux de paiement. Vous pouvez également vouloir collecter différents détails de carte auprès du payeur parce que les détails collectés précédemment ne sont pas acceptables, par exemple la marque de la carte n'est pas acceptée.
HostedForm.updateSession(sessionId, sessionDetails, updateSessionCallback);
Voici un exemple de code qui montre comment appeler la méthode HostedForm.updateSession() pour mettre à jour une session existante.
// Collect the card details based on the 'id' of the form elements
var getSessionDetailsFromForm = function() {
return {
cardNumber: document.getElementById('cardNumber').value,
cardSecurityCode: document.getElementById('cardSecurityCode').value,
cardExpiryMonth: document.getElementById('expiryMonth').value,
cardExpiryYear: document.getElementById('expiryYear').value
}
}
// Call doCheckoutWithExistingSession() from the form submit onClick() event
var doCheckoutWithExistingSession = function(sessionId) {
var sessionDetails = getSessionDetailsFromForm();
HostedForm.updateSession(sessionId, sessionDetails, callback);
};
Quand Mastercard Gateway traite votre formulaire, la réponse est gérée par une fonction de rappel que vous devez définir dans votre page Web. Cette fonction reçoit un objet décrivant le résultat de l'appel à HostedForm.createSession( ) ou HostedForm.updateSession( ).
Si response.status contient « ok », votre page Web doit transmettre l'identificateur de session renvoyé à votre serveur Web afin qu'il puisse l'utiliser pour appeler une transaction. Si response.status contient 'fields_in_error', votre page Web doit analyser individuellement les champs pour rechercher les erreurs. Pour les codes d'erreur, voir Gestion des erreurs de formulaire de paiement.
Voici un exemple de code qui inclut l'identificateur de session et l'élément de marque de carte dans le formulaire de paiement soumis à votre navigateur Web.
var callback = function(response) {
if (response.status === "ok") {
// call your server to do the payment with the response.session value
// this is where we populate the hidden values in the form
var sessionIdElement = document.getElementById("sessionId");
sessionIdElement.value = response.session;
// card brand is not required to be submitted, but shown here as an optional field
// the response object contains the full list of fields
var cardBrandElement = document.getElementById("cardBrand");
cardBrandElement.value = response.cardBrand;
document.myform.submit();
} else if (response.status === "request_timeout") {
// handle the timeout for example by giving the payer the possibility to retry
} else if (response.status === "fields_in_error") {
// check in the response.fieldsInError object to see which field was marked as invalid or missing
if (response.fieldsInError.cardNumber === "invalid") {
document.getElementById('cardNumber').style.color="red";
} else if (response.fieldsInError.cardExpiryMonth === "invalid") {
document.getElementById('expiryMonth').style.color="red";
} else if (response.fieldsInError.cardExpiryYear === "invalid") {
document.getElementById('expiryYear').style.color="red";
} else if (response.fieldsInError.cardSecurityCode === "invalid") {
document.getElementById('cardSecurityCode').style.color="red";
}
}
} else if (response.status === "invalid_session") {
// handle invalid session details for example by giving the payer the possibility to retry with different card details. If the new details are correct, you can call the updateSession( ) method
} else {
// add system error handling here. Typically this would mean the integration is not working properly because there is no response from the client library.
// this could result in displaying a page to the payer to try again later and call support
}
};