Implémentation de la Hosted Payment Page
Vous disposez de deux options pour implémenter la Hosted Payment Page :
- La page intégrée est un composant activé dans la page de paiement existante de votre site Web.
- La page de paiement est une page distincte vers laquelle le payeur est redirigé à partir de la page de paiement existante.
Une fois qu'une session de paiement a été établie, le processus d'implémentation de la Hosted Payment Page pour Hosted Checkout se compose des étapes suivantes :
- Créer un objet Checkout.
- Configurer l'objet Checkout.
- Utiliser la méthode appropriée de l'objet Checkout pour démarrer le processus de paiement.
En outre, vous pouvez définir des rappels qui sont déclenchés lorsque le payeur effectue certaines actions au cours du traitement du paiement.
L'implémentation de la Hosted Payment Page se fait dans votre application ou sur votre site Web, à l'aide de la bibliothèque Checkout JavaScript (JS).
Étape 1 : Créer l'objet Checkout
Une fois la session initialisée, vous devez vous référer au fichier checkout.min.js du serveur de passerelle sur votre page de paiement. Cela place un objet Checkout dans l'étendue globale.
<script src="https://ap-gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
Étape 2 : Configurer l'objet Checkout
Appelez la fonction Checkout.configure() et transmettez-lui un objet JSON qui inclut le session.id renvoyé par l'opération Initiate Checkout (Lancer le paiement) précédente.
Checkout.configure({
session: {
id: '<your_initiate_checkout_ID>'
}
});
- À compter de la version 67 ou une version ultérieure, l'objet session est le seul champ autorisé via configure() ; tous les autres champs doivent être inclus via INITIATE CHECKOUT (Lancer le paiement).
- Les données transmises dans Checkout.configure() n'écrasent jamais les données celles fournies lors de l'opération INITIATE CHECKOUT (Lancer le paiement).
Étape 3 : Lancer le traitement de paiement
Lancez le traitement de paiement en appelant l'une des méthodes suivantes de l'objet Checkout, en fonction du type deHosted Payment Page que vous implémentez.
- Pour afficher l'interaction de paiement sur une page intégrée :
Exemple
Checkout.showEmbeddedPage('#embed-target') - Pour afficher l'interaction de paiement sur une page de paiement :
Exemple
Checkout.showPaymentPage()
Exemple de code HTML pour demander la page intégrée ou de paiement
<html>
<head>
<script src="https://ap-gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
<script type="text/javascript">
function errorCallback(error) {
console.log(JSON.stringify(error));
}
function cancelCallback() {
console.log('Payment cancelled');
}
Checkout.configure({
session: {
id: '<your_initiate_checkout_session_ID>'
}
});
</script>
</head>
<body>
...
<div id="embed-target"> </div>
<input type="button" value="Pay with Embedded Page" onclick="Checkout.showEmbeddedPage('#embed-target');" />
<input type="button" value="Pay with Payment Page" onclick="Checkout.showPaymentPage();" />
...
</body>
</html>
Exemple de code HTML pour utiliser le mode modal
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous">
<title>Hello, world!</title>
</head>
<body>
<h1>Hello, world!</h1>
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
Launch demo modal
</button>
<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog" role="document">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
<button type="button" class="close" data-dismiss="modal" aria-label="Close">
<span aria-hidden="true">—</span>
</button>
</div>
<div class="modal-body" id="hco-embedded">
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
<button type="button" class="btn btn-primary">Save changes</button>
</div>
</div>
</div>
</div>
<script src="https://code.jquery.com/jquery-3.6.0.slim.min.js" integrity="sha256-u7e5khyithlIdTpu22PHhENmPcRdFiHRjhAuHcs05RI=" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@4.5.2/dist/js/bootstrap.min.js" crossorigin="anonymous"></script>
<script src="https://ap-gateway.mastercard.com/static/checkout/checkout.min.js" ></script>
<script>
// Configure Checkout first
Checkout.configure({
session: {
id: "<your_initiate_checkout_ID>"
}
})
// after the modal is shown, then call Checkout.showEmbeddedPage('#hco-embedded')
$('#exampleModal').on('shown.bs.modal', function (e) {
Checkout.showEmbeddedPage('#hco-embedded',
() => { $('#exampleModal').modal() } // tell Checkout how to launch the modal
)
});
$('#exampleModal').on('hide.bs.modal', function (e) {
sessionStorage.clear(); // tell Checkout to clear sessionStorage when I close the modal
});
</script>
</body>
</html>
Étape 4 : Implémenter les rappels
Des rappels sont fournis pour gérer les événements pouvant survenir lors de l'interaction de paiement. L'utilisation de rappels est facultative, mais si vous en avez besoin, vous devez les définir dans le corps de la même balise <script> qui fait référence à checkout.min.js.
Tous les rappels définis doivent avoir une implémentation. Ils sont appelés lorsque l'événement concerné est déclenché. L'exemple de code suivant montre un exemple de rappel (déclenché si le payeur annule le paiement) défini et implémenté sur une page.
<script src="https://ap-gateway.mastercard.com/static/checkout/checkout.min.js"
data-cancel="cancelCallback"
data-beforeRedirect="Checkout.saveFormFields"
data-afterRedirect="Checkout.restoreFormFields">
</script>
<script>
function cancelCallback() {
confirm('Are you sure you want to cancel?');
// code to manage payer interaction
}
// or if you want to provide a URL:
// cancelCallback = "someURL"
</script>
Il existe deux types de méthodes de rappel : les rappels de base et les rappels de redirection.
Rappels de base
Les rappels de base sont fournis pour les événements suivants :
- cancel : le payeur annule l'interaction de paiement.
Le rappel d'annulation ne peut être utilisé qu'avec une page de paiement ; il ne fonctionne pas avec une page intégrée.
- error : une erreur est survenue.
- complete : le payeur termine l'interaction de paiement.
- timeout : le paiement n'est pas terminé dans les temps impartis pour que le payeur puisse effectuer le paiement.
Rappels de redirection
Hosted Checkout prenant en charge les interactions de paiement qui requièrent la redirection du payeur vers d'autres sites Web afin de faire progresser le paiement (par exemple PayPal), les rappels permettent de gérer ce qui se passe avant la redirection et après le retour Hosted Checkout pour finaliser le traitement de la transaction.
- beforeRedirect : avant que l'interface de paiement ne soit présentée au payeur. Renvoie les données requises pour restaurer l'état de l'interface de paiement à utiliser par afterRedirect.
- afterRedirect : lors du retour du payeur une fois l'interaction de paiement terminée. Utilise les données enregistrées par beforeRedirect pour rétablir l'état enregistré de l'interface de paiement.
L'objet Checkout fournit également deux fonctions pour vous aider à implémenter les rappels beforeRedirect et afterRedirect :
- saveFormFields() : enregistre tous les champs de formulaire actuels pour une utilisation par restoreFormFields(). Utilisez-le dans votre implémentation beforeRedirect ou implémentez beforeRedirect en tant que Checkout.saveFormFields().
- restoreFormFields() : restaure les champs de formulaire enregistrés par saveFormFields(). Utilisez-le dans votre implémentation afterRedirect ou implémentez afterRedirect en tant que Checkout.restoreFormFields().
Questions fréquentes
Que faire si Hosted Checkout retourne une erreur ?
Hosted Checkout peut retourner un certain nombre d'erreurs d'intégration. Pour plus d'informations sur les tests et les erreurs, voir Étapes de test.
Pourquoi est-ce que je reçois une page d'erreur au lieu de la Hosted Payment Page ?
Une page d'erreur s'affiche lorsqu'une demande Hosted Checkout incorrecte est tentée. Les causes courantes d'erreur sont notamment :
- Des champs obligatoires manquants.
- Les URL fournies dans la demande ne sont pas absolues.
Que se passe-t-il si le payeur double-clique sur le bouton Payer ?
Si le payeur double-clique sur le bouton Payer, c'est-à-dire qu'il soumet le paiement deux fois, la transaction n'est pas répétée auprès de votre banque ou de celle du payeur.