Carte-cadeau
Mastercard Gateway vous permet d'offrir des cartes-cadeaux à vos payeurs comme mode de paiement.
Conditions préalables
- Vous devez vous inscrire auprès d'un fournisseur tiers spécialisé dans ce domaine.
- Votre Your payment service provider doit configurer votre profil de commerçant Mastercard Gateway en utilisant les détails de votre compte auprès du fournisseur tiers.
Ajouter des cartes-cadeaux à votre intégration
La passerelle propose trois options permettant d'intégrer les cartes-cadeaux à votre page de paiement.
Cartes-cadeaux via Hosted Checkout
Si vous disposez d'une intégration Hosted Checkout existante, vous pouvez utiliser Hosted Checkout pour vérifier les détails de la carte-cadeaux.
Pour ce faire, vous pouvez définir interaction.operation=VERIFY dans la demande Créer une session de paiement. Hosted Checkout affiche la carte-cadeaux comme option de paiement pour le payeur. Les données saisies par le payeur sont vérifiées avec les méthodes de vérification prises en charge par l'acquéreur configuré.
Vous pouvez savoir si l'opération de vérification a réussi en comparant les paramètres resultIndicator et successIndicator. Si l'interaction échoue, Hosted Checkout affiche un message indiquant que la vérification a échoué et invite le payeur à réessayer.
Cartes-cadeaux via Hosted Session
Si vous disposez de votre propre page de paiement, vous pouvez choisir l'option d'intégration Hosted Session pour que Mastercard Gateway collecte les détails de la carte-cadeaux en toute sécurité et les stocke dans une session de paiement.
<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 Gift Card details:</div>
<div>Card Number: <input type="text" id="gift-card-number" class="input-field" value="" readonly></div>
<div>Pin:<input type="text" id="gift-card-pin" class="input-field" value="" 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;
}
PaymentSession.configure({
fields: {
// ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A GIFT CARD
giftCard: {
number: "#gift-card-number",
pin: "#gift-card-pin",
}
},
//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);
} else if ("fields_in_error" == response.status) {
console.log("Session update failed with field errors.");
if (response.errors.number) {
console.log("Gift card number invalid or missing");
}
if (response.errors.pin) {
console.log("Pin 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);
}
}
}
});
function pay() {
// UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
PaymentSession.updateSessionFromForm('giftCard', '<localCardBrand>');
}
</script>
</body>
</html>
- Incluez la bibliothèque JavaScript client
session.jshébergée par la passerelle dans votre page de paiement. Le chemin vers ce fichier comporte la version de l'API et l'ID du commerçant pour la session. - Créez le formulaire HTML pour la page de paiement comportant les champs de carte-cadeaux.
Pour empêcher la soumission de données sensibles au serveur, assurez-vous que les champs des données sensibles sont enreadonlyet n'ont PAS l'attributname. - Appelez la fonction
PaymentSession.configure(configuration).
L'objet
configurationvous permet de rattacher des champs hébergés à votre page de paiement. Vous devez indiquer les éléments suivants :
- la session (facultatif) ; si vous n'en indiquez pas, la bibliothèque client crée une session de paiement ;
- Les sélecteurs de champ pour les champs de carte-cadeaux 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 ;
- 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 javascriptincluez le JavaScript « frame-breaker » dans votre page de paiement. x-frame-optionsVotre serveur doit retourner un en-tête de réponse HTTP X-Frame-Options. cspVotre serveur doit retourner l'en-tête de réponse HTTP Content-Security-Policy comportant une directive « frame-ancestors ». Vous devez spécifier quelles défenses sont implémentées via le
frameEmbeddingMitigationparamètre dans l'PaymentSession.configure(configuration)appel. 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('giftCard', <localCardBrand>)(voir étape suivante)
- Appelez la fonction
PaymentSession.updateSessionFromForm('giftCard', <localCardBrand>)pour stocker les détails de la carte-cadeaux collectés dans une session de paiement. Lorsque l'opération est terminée, la fonction de rappelformSessionUpdate( )est appelée avec un paramètre de résultat. Vous devez vérifier la valeur deresult.statusafin de déterminer si l'opération a réussi. Voir Gestion des réponses des rappels. - 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.
Référence de session.js[JavaScript]
Cartes-cadeaux via Direct Payment
Pour bénéficier d'un contrôle total sur l'interaction avec les cartes-cadeaux sur votre page de paiement, vous pouvez choisir l'option Direct Payment.
Demander une autorisation ou un paiement par carte cadeau
Vous devez renseigner les champs suivants dans la demande Authorize (Autoriser) :
sourceOfFunds.type=GIFT_CARDsourceOfFunds.provided.giftCard.number: Numéro de la carte-cadeau.sourceOfFunds.provided.giftCard.pin: Code PIN de la carte-cadeau. (Pas toujours obligatoire, selon la carte-cadeau.)order.amount: Montant à payer.order.currency: Devise du paiement.order.acceptPartialAmount: (Facultatif) Indique si vous êtes prêt à accepter la carte pour un paiement partiel du montant total. La valeur par défaut de ce paramètre estFALSE.
Outre les champs standard, les champs suivants sont retournés pour une autorisation réussie :
sourceOfFunds.type:GIFT_CARD, mise en miroir de votre demande.sourceOfFunds.provided.giftCard.number: numéro de la carte-cadeau (masqué).sourceOfFunds.provided.giftCard.pin: code PIN de la carte-cadeau (entièrement masqué).sourceOfFunds.provided.giftCard.scheme: organisme qui possède une marque de carte-cadeau et définit les règles concernant son utilisation.sourceOfFunds.provided.giftCard.brand: Marque servant à décrire la carte-cadeau qui est reconnue et acceptée dans le monde entier. Pour de nombreux types de carte répandus, il s'agit du nom du système.sourceOfFunds.provided.giftCard.localBrand: nom de marque utilisé pour décrire une carte-cadeau tel que déterminé par la passerelle en fonction de la plage BIN de la carte.availableBalance.funds.amount: montant utilisable par le payeur au moyen de cette carte-cadeau après ce paiement. (La fourniture de ces informations dépend du fournisseur tiers.)availableBalance.funds.currency: devise du solde disponible sur la carte exprimée en un code ISO 4217 alphanumérique, par exemple USD.order.amount: montant accepté. Notez qu'il peut être inférieur au montant demandé si la carte ne dispose pas de fonds suffisants et que vous avez définiorder.acceptPartialAmount=TRUE.transaction.requestedAmount: si la transaction a été partiellement approuvée (response.gatewayCode=PARTIALLY_APPROVED), ce paramètre contient le montant demandé initialement.
Si vous avez définiorder.acceptPartialAmount=TRUE,transaction.amountetorder.amountcorrespondent au montant réellement approuvé.
Vérifier la carte cadeau
Vous pouvez vérifier qu'une carte-cadeau dotée d'un numéro de carte et d'un code PIN valides est une carte valable émise par le fournisseur en soumettant une demande DirectAPIVERIFY (Vérifier).
Référence de l'API Verify (Vérifier) [REST][NVP]
Demande de solde
Vous pouvez demander des renseignements sur le solde d'une carte-cadeau en soumettant une demande DirectAPI BALANCE_INQUIRY. Vous devez renseigner les champs suivants dans la demande :
sourceOfFunds.type=GIFT_CARDsourceOfFunds.provided.card.number: Le numéro de la carte-cadeau pour laquelle vous demandez des informations sur le solde.
Référence de l'API Balance Inquiry (Demande de solde)[REST][NVP]
Gérer les approbations partielles
Si vous êtes prêt à accepter une approbation d'un montant partiel pour une transaction via une carte-cadeau, vous devez soumettre order.acceptPartialAmount=TRUE dans votre demande. Dans ce cas, vous êtes responsable de créer une autre transaction pour le solde impayé en utilisant un autre mode de paiement.
Si vous n'êtes pas prêt à le faire, définissez order.acceptPartialAmount=FALSE dans votre demande. Si les fonds de la carte-cadeau sont insuffisants, Mastercard Gateway répondra avec response.gatewayCode=INSUFFICIENT_FUNDS.
Référence de l'API Card Details (Détails de la carte)[REST][NVP]
Test et mise en service
Vous pouvez tester l'intégration de votre carte-cadeau au moyen de votre profil d'essai de commerçant.