Guide de configuration

Configuration du Centre de ressources pour commerçants

La première étape consiste à configurer la page Moneris Checkout dans le Centre de ressources pour commerçants (CRC) de Moneris.

Pendant le développement, créer une configuration d'essai dans le CRC d'essai. Lorsque la solution est prête à être déployée, créer une configuration distincte dans le CRC de production.

Le Checkout ID est produit une fois la configuration terminée. Il sert à désigner une configuration Moneris Checkout précise dans la demande Preload.

Pour obtenir le Checkout ID et amorcer la configuration de la page, effectuer les étapes suivantes :

Pour personnaliser la configuration du Centre de ressources pour commerçants, consulter le guide de référence du Centre de ressources pour commerçants.

Page de paiement côté client

Pour préparer la page de paiement côté client en vue de l'intégration de Moneris Checkout, effectuer les tâches suivantes :

Choisir une version de la bibliothèque Moneris Checkout

Importer la bibliothèque JavaScript de Moneris Checkout au moyen d'une balise <script>. Deux options s'offrent aux commerçants, selon les exigences de conformité de l'entreprise en matière de gestion des versions et d'intégrité des scripts. Dans les deux cas, les scripts sont transmis par HTTPS et protégés pendant leur transmission, en plus des contrôles d'intégrité appliqués sur le serveur.

Option A : intégration standard

Cette option garantit que l'intégration utilise toujours la plus récente version stable du script de paiement provenant du réseau de diffusion de contenu de Moneris. Le code HTML n'a donc pas à être modifié lors de la publication de nouvelles versions.

<script src="https://gatewayt.moneris.com/chktv2/js/chkt_v3.00.js"></script>

Ou la version minifiée :

<script src="https://gatewayt.moneris.com/chktv2/js/chkt_v3.00.min.js"></script>

<script src="https://gateway.moneris.com/chktv2/js/chkt_v3.00.js"></script>

Ou la version minifiée :

<script src="https://gateway.moneris.com/chktv2/js/chkt_v3.00.min.js"></script>

Option B : intégrité des sous-ressources (SRI)

Cette option permet de mettre en œuvre l'intégrité des sous-ressources (SRI) dans les environnements qui exigent une validation supplémentaire de l'intégrité des scripts, à des fins de conformité ou en vertu de politiques de sécurité internes. Avec la SRI, le navigateur vérifie que le contenu du script correspond à la valeur de hachage fournie avant de charger le formulaire MCO.

<script 
    src="https://gatewayt.moneris.com/chktv2/js/chkt_v3.00.js"
    integrity="sha384-2Imusztg9T9G7DWhK7HYDWkOK3rbel4csnr3V5x1WDvEIKo+CO6kTi6naz21cbVw"
    crossorigin="anonymous"
></script>

Ou la version minifiée :

<script 
    src="https://gatewayt.moneris.com/chktv2/js/chkt_v3.00.min.js"
    integrity="sha384-/SFtfaZKoxmvtlAhg8OeYsit8YegNgyeR5AN6gc3x0Y43URbFtpo3MpLcE55F/ld"
    crossorigin="anonymous"
></script>

<script 
    src="https://gateway.moneris.com/chktv2/js/chkt_v3.00.js"
    integrity="sha384-2Imusztg9T9G7DWhK7HYDWkOK3rbel4csnr3V5x1WDvEIKo+CO6kTi6naz21cbVw"
    crossorigin="anonymous"
></script>

Ou la version minifiée :

<script 
    src="https://gateway.moneris.com/chktv2/js/chkt_v3.00.min.js"
    integrity="sha384-/SFtfaZKoxmvtlAhg8OeYsit8YegNgyeR5AN6gc3x0Y43URbFtpo3MpLcE55F/ld"
    crossorigin="anonymous"
></script>

Créer le conteneur de paiement

Créer un élément <div> portant l'identifiant monerisCheckout. La bibliothèque utilise cet élément pour intégrer la page de paiement.

Par défaut, la page de paiement s'ouvre en mode plein écran :

<div id="monerisCheckout"></div>

Pour utiliser des dimensions personnalisées, insérer le conteneur monerisCheckout dans un élément <div> parent et définir les dimensions souhaitées :

<div id="outerDiv" style="width:400px; height:300px">
  <div id="monerisCheckout"></div>
</div>

Lancer le paiement

Prévoir un événement déclencheur pour amorcer le paiement, par exemple un clic sur un bouton. Cette étape récupère le ticket de transaction sécurisé auprès du serveur, intègre les champs de Moneris Checkout dans le conteneur défini précédemment, enregistre les fonctions de traitement des rappels, puis lance le paiement.

// Récupérer le ticket de transaction sécurisé auprès du serveur
const response = await fetch(
    "http://localhost:3000/api/initiate-checkout",
  {
    method: "POST",
  }
);
const data = await response.json();

if (!data.ticket) {
  throw new Error("No tickets returned from payment initialization endpoint");
}

// Créer l'instance Moneris Checkout et définir le conteneur d'intégration
const myCheckout = new monerisCheckout();
myCheckout.setMode("qa"); // Utiliser "prod" en production
myCheckout.setCheckoutDiv("monerisCheckout");

// Enregistrer les rappels requis pour le cycle de vie et les transactions
myCheckout.setCallback("page_loaded", handlePageLoaded);
myCheckout.setCallback("cancel_transaction", handleCancelTransaction);
myCheckout.setCallback("error_event", handleErrorEvent);
myCheckout.setCallback("payment_receipt", handlePaymentReceipt);
myCheckout.setCallback("payment_complete", handlePaymentComplete);

// Afficher l'interface de paiement hébergée dans le conteneur
myCheckout.startCheckout(data.ticket);

Logique serveur à serveur

Le processus de paiement exige deux appels serveur à serveur : le premier lance le paiement, le second récupère le reçu une fois le paiement terminé. Les deux demandes utilisent le même point de terminaison, mais avec des propriétés différentes.

Dans la mise en œuvre côté serveur, transmettre les demandes POST aux adresses Moneris Checkout suivantes, selon l'étape du développement :

Demande Preload

La demande Preload crée de façon sécurisée une instance Moneris Checkout au moment de la transaction. Il s'agit d'une demande POST serveur à serveur qui utilise le format JSON décrit dans la page Demande Preload.

La réponse à la demande Preload contient un numéro de ticket qui désigne l'instance de paiement de façon unique. Transmettre ce ticket à myCheckout.startCheckout(ticketNumber) pour afficher Moneris Checkout dans le navigateur.

Note : le numéro de ticket expire après 30 minutes.

Transmettre une demande POST à /chktv2/request/request.php avec le corps suivant :

{
  "store_id": "store2", // Remplacer par le Store ID de Moneris
  "api_token": "yesguy", // Remplacer par le jeton d'API de Moneris
  "checkout_id": "chktBA8VTtore2", // Remplacer par le Checkout ID obtenu
  "txn_total": "100.00", // Montant total de la transaction
  "environment": "qa", // "qa" pour l'essai, "prod" pour la production
  "action": "preload"
}

Pour connaître les autres paramètres, consulter la page Référence de l'API – Demande Preload.

Demande Receipt

Une fois le rappel payment_complete reçu, le site Web peut transmettre la demande Receipt serveur à serveur pour obtenir les détails de la transaction nécessaires au reçu et savoir si la transaction a été approuvée ou refusée.

Transmettre une demande POST à /chktv2/request/request.php avec le corps suivant :

{
  "store_id": "store2", // Remplacer par le Store ID de Moneris
  "api_token": "yesguy", // Remplacer par le jeton d'API de Moneris
  "checkout_id": "chktBA8VTtore2", // Remplacer par le Checkout ID obtenu
  "ticket": "1782309276washiedRIyaLlbruGuR02UobXJXUAT", // Numéro de ticket de la demande Preload
  "environment": "qa", // "qa" pour l'essai, "prod" pour la production
  "action": "receipt"
}

Pour connaître les autres paramètres, consulter la page Référence de l'API – Demande Receipt.

Traitement des rappels

Les rappels permettent à Moneris Checkout de communiquer avec la page de paiement du commerçant. Chaque rappel comporte un seul paramètre, défini sous forme de chaîne au format JSON.

Pour traiter les rappels, créer des fonctions JavaScript qui reçoivent les rappels transmis par Moneris Checkout au moment où les événements se produisent.

Champs de réponse des rappels

Rappel de chargement de la page (page_loaded)

Utilisation du rappel

Ce rappel indique l'état de chargement de la page Moneris Checkout. Il est déclenché une fois Moneris Checkout chargé.

Méthode JavaScript pour définir le rappel

myCheckout.setCallback("page_loaded",myPageLoad);

Exemple de réponse JSON :

{
  "handler":"page_loaded",
  "ticket":"1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
  "response_code":"001"
}

Rappel d'annulation de la transaction (cancel_transaction)

Utilisation du rappel :

Ce rappel est déclenché lorsque le titulaire de carte clique sur le bouton d'annulation dans Moneris Checkout. La pratique courante consiste à appeler la méthode closeCheckout() pour fermer Moneris Checkout. Cette méthode doit être appelée, et une nouvelle demande Preload est nécessaire pour créer une nouvelle instance Moneris Checkout.

Méthode JavaScript pour définir le rappel :

myCheckout.setCallback("cancel_transaction",myCancelTransaction);

Exemple de réponse JSON :

{
  "handler":"cancel_transaction",
  "ticket":"1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
  "response_code":"001"
}

Rappel de reçu de paiement (payment_receipt)

Utilisation du rappel :

La transaction est terminée et le reçu est prêt à être récupéré. Si Moneris Checkout est configuré pour produire le reçu, ce rappel est déclenché une fois le reçu de la transaction affiché. Si Moneris Checkout n'est pas configuré pour produire un reçu, ce rappel n'est pas déclenché. Pour savoir à quel moment obtenir la réponse du reçu de la transaction, consulter le rappel de paiement terminé.

Méthode JavaScript pour définir le rappel :

myCheckout.setCallback("payment_receipt",myPaymentReceipt);

Exemple de réponse JSON :

{
  "handler": "payment_receipt",
  "ticket": "1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
  "response_code": "001"
}

Rappel de paiement terminé (payment_complete)

Utilisation du rappel :

Ce rappel est déclenché une fois le paiement traité par Moneris Checkout. Si Moneris Checkout est configuré pour produire un reçu, le titulaire de carte doit revenir à la page de paiement du commerçant pour que le rappel soit déclenché. Pour savoir comment obtenir la réponse du reçu de la transaction, consulter le rappel de reçu de paiement. Moneris Checkout doit ensuite être fermé au moyen de la méthode closeCheckout().

Méthode JavaScript pour définir le rappel :

myCheckout.setCallback("payment_complete",myPaymentComplete);

Exemple de réponse JSON :

{
  "handler":"payment_complete",
  "ticket":"1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
  "response_code":"001"
}

Rappel de fermeture de la page (page_closed)

Utilisation du rappel :

Ce rappel est déclenché lorsque le titulaire de carte, après avoir soumis son paiement dans la page de paiement, tente de fermer la fenêtre, clique sur le bouton de retour du navigateur ou actualise la page avant la confirmation du paiement, ce qui provoque une erreur JavaScript.
Moneris Checkout doit être fermé au moyen de la méthode closeCheckout(). Le paiement se poursuit normalement, sans modification au déroulement.

Méthode JavaScript pour définir le rappel :

myCheckout.setCallback("page_closed",myPageClosed);

Exemple de réponse JSON :

Lorsque le titulaire de carte ferme la fenêtre, clique sur le bouton de retour ou actualise la page dans le navigateur :

{
  "handler":"page_closed", 
  "response_code":"001"
}

Lorsqu'une erreur JavaScript se produit :

{
  "handler":"page_closed",
  "ticket":"1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
  "response_code":"001"
}

Rappel de soumission du paiement (payment_submitted)

Utilisation du rappel :

Ce rappel est déclenché lorsque le titulaire de carte clique sur le bouton de paiement et que le traitement du paiement commence.

Méthode JavaScript pour définir le rappel :

myCheckout.setCallback("payment_submitted",myPaymentSubmitted);

Exemple de réponse JSON :

{
  "handler":"payment_submitted",
  "ticket":"1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
  "response_code":"001"
}

Finalisation du paiement

Déclenchement du paiement

Lorsque le client amorce le paiement, la page Moneris Checkout s'affiche dans le conteneur <div> du site Web.

Pour afficher l'instance Moneris Checkout dans le conteneur, appeler myCheckout.startCheckout(ticketNumber).

Fin du paiement

Pour mettre fin à l'instance Moneris Checkout, appeler myCheckout.closeCheckout().

Mise à l'essai de l'intégration

À l'étape des essais :

1. Utiliser le Centre de ressources pour commerçants d'essai, à l'adresse https://esqa.moneris.com/mpg, pour configurer la page Moneris Checkout aux fins des essais.
2. Utiliser l'adresse d'essai pour les demandes serveur à serveur :
   https://gatewayt.moneris.com/chktv2/request/request.php
3. Référencer la bibliothèque JavaScript d'essai indiquée à la section Choisir une version de la bibliothèque Moneris Checkout.

<script src="https://gatewayt.moneris.com/chktv2/js/chkt_
v2.01.js"></script>

<script src="https://gatewayt.moneris.com/chktv2/js/chkt_v2.01.js" integrity="sha384-jCchnHgslEZApz6/VsHOhc8KmLypSa5AnuZIAMkfPqAqlFpJw+LR9Tion5O/3tz6"
crossorigin="anonymous"></script>

4. Régler l'objet myCheckout au mode d'essai : myCheckout.setMode("qa");
5. Dans toutes les demandes, utiliser la valeur « qa » pour la variable environment et s'assurer d'utiliser la version d'essai des identifiants Store ID, API token et Checkout ID.

Cartes d'essai

Lors des essais, il est possible d'utiliser les numéros de carte suivants, avec n'importe quelle date d'expiration à venir.

Mise à l'essai des frais de commodité ou des frais de service

Pour mettre à l'essai des transactions comportant des frais de commodité ou des frais de service dans Moneris Checkout, utiliser les identifiants d'essai suivants :

Store ID: monca00392 
API token: qYdISUhHiOdfTr1CLNpN
Username: DemoUser
Password: password

Mise à l'essai 3DS

Pour mettre à l'essai une intégration 3-D Secure, consulter la documentation suivante : https://legacy-developer.moneris.com/More/Testing/Testing%203D%20Solutions

Passage en production avec MCO

Une fois les essais de l'intégration Moneris Checkout terminés, effectuer les étapes suivantes pour passer en production :

1. S'assurer que la configuration d'essai finale a été reproduite dans la configuration Moneris Checkout de production, dans le Centre de ressources pour commerçants de production, à l'adresse https://www3.moneris.com/mpg.
2. Utiliser l'adresse de production pour les demandes serveur à serveur :
   https://gateway.moneris.com/chkt/request/request.php
3. Utiliser la bibliothèque JavaScript de production :
   HTML

   <script src="https://gateway.moneris.com/chktv2/js/chkt_v3.00.js"></script>

4. Régler l'instance de paiement au mode de production :
   JavaScript

   myCheckout.setMode("prod");

5. Dans toutes les demandes, utiliser la valeur « prod » pour la variable environment et s'assurer d'utiliser la version de production des identifiants Store ID, API token et Checkout ID.

Considérations relatives à la conformité

Les exigences de la norme PCI DSS peuvent varier selon l'intégration de paiement et sa mise en œuvre. Examiner les exigences de conformité applicables à l'entreprise avant le passage en production. Pour en savoir plus, consulter la page Conformité.