KONEK

Vue d'ensemble

KONEK™ est la nouvelle solution de passerelle de paiement numérique offerte par Interac®. Elle permet aux consommateurs d'effectuer leurs achats en ligne et de payer les biens et services directement par l'entremise de leur institution financière (service Pay By Bank). Le flux de paiement des transactions KONEK relie les commerçants, les acquéreurs, Interac®, les institutions financières (IF) et d'autres réseaux de cartes. Les modes de paiement offerts avec cette nouvelle solution incluent :

Paiements basés sur le compte (Pay By Bank) : les clients peuvent payer directement à partir de leur compte bancaire à l'aide des identifiants qu'ils connaissent déjà. Cela réduit la dépendance aux cartes et peut diminuer les frictions opérationnelles pour les commerçants.
Paiements par carte : KONEK prend également en charge les transactions par carte de débit et de crédit, assurant la continuité de vos processus de paiement existants.

Interac Direct est un nouveau service d'API offert par Interac® pour le traitement des paiements par compte bancaire amorcés par l'entremise du service de paiement numérique KONEK. Interac Direct fournit toutes les fonctionnalités d'une option de paiement de commerce numérique. Les types de transactions pris en charge par la solution Interac Direct comprennent les paiements uniques, les paiements préautorisés et les transactions de remboursement.

Intégration du commerçant à l'API Moneris

Pour commencer à utiliser KONEK en tant que commerçant utilisant l'API Moneris, deux composantes principales doivent être configurées :

Implémenter le SDK KONEK.
Implémenter le processus de gestion des consentements KONEK au moyen des API Moneris (KONEK).

Notez que l'intégration n'est pas destinée à être implémentée sans s'appuyer sur les spécifications de l'API Moneris (documentation à l'appui) disponibles dans le portail des développeurs Moneris ainsi que la documentation d'accompagnement fournie par le conseiller-client du commerçant.

📘
Activation du compte requise
KONEK doit être activé dans votre profil de commerce API Moneris avant que vous puissiez procéder à l'intégration. Communiquez avec votre conseiller-client Moneris pour demander l'activation et obtenir les spécifications de l'API Moneris qui accompagnent ce guide.
Spécification de l’API Moneris
Courriel :
[email protected]

Diagramme de flux — Commerçants API et KONEK

Le diagramme ci-dessous illustre le processus permettant aux commerçants utilisant l'API de s'intégrer à KONEK.

Implémentation du SDK KONEK

Importer le SDK

Pour importer le SDK du commerçant, ajoutez une balise script dans la section <head> avec le lien vers konek-sdk.esm.js. Il s'agit uniquement du script d'entrée, qui détectera la configuration du navigateur et déclenchera l'importation du reste des fichiers JavaScript optimisés du SDK.

<script type="module" src="https://sdk.fit1.konek.dev/konek-sdk/konek-sdk.esm.js"></script>

📘
URL du SDK de production
Lorsque vous passez en production, remplacez l'URL de certification ci-dessus par : https://sdk.konek.ca/konek-sdk/konek-sdk.esm.js
Consultez la section
Passage à la production

Ajouter un bouton « Pay with KONEK »

Pour ajouter un bouton « Pay with KONEK » à une page Web, utilisez la balise <konek-button-v1>.

<konek-button-v1 border-radius="4" height="34" width="100" color="black"></konek-button-v1>

📘
Propriétés du bouton
Les détails sur les propriétés de ce bouton se trouvent dans la section Propriétés du bouton KONEK.
Propriétés du bouton KONEK

Obtenir une référence à l'élément HTML

Obtenez la référence de l'élément HTML (konek-button-v1) au moyen d'un sélecteur de requête document. La référence est nécessaire pour attacher différents écouteurs d'événements. L'objet konekClient doit également être accessible via la propriété client de l'élément, car il est requis pour distribuer les événements amorçant le processus de paiement ainsi qu'à des fins de débogage.

📘
Événements des boutons
Les détails concernant les événements sont abordés dans la section Événements du bouton KONEK.
Événements du bouton KONEK

Écouteur de l'événement onclick

L'écouteur de l'événement click du konek-button-v1 doit servir à effectuer un appel à l'API Create KONEK Payment Consent. Appelez la méthode addOverlay de konekClient pour afficher une superposition (overlay) pendant que d'autres tâches asynchrones s'exécutent en arrière-plan.

// Add click event listener to konek-button
konek.addEventListener('click', event => {
  // 1. Show overlay message while continuing other async tasks
  konek.client.addOverlay();

  // 2. Call merchant BE to pass cart data
  try {
    let consentResponse = await fetch(MERCHANT_BE_URL, {
      method: 'POST',
      headers: {
        'Content-type': 'application/json',
      },
    });

    // 3. MERCHANT BE response
    const { consentId, correlationId, deviceProfileSessionId, totalAmount, merchantName } =
      consentResponse;

    // 4. Call setConsentData method of konek client
    konek.client.setConsentData({
      consentId,
      correlationId,
      deviceProfileSessionId,
      totalAmount,
      merchantName
    });
  } catch (e) {
    // 5. On error pass error code
    konek.client.setConsentError({ error: 'createConsentFailed' });
  }
});

Des données supplémentaires propres au commerçant doivent être incluses dans la charge utile de création du consentement. Consultez le schéma Créer un consentement de paiement KONEK dans les spécifications de l'API Moneris.

Une fois qu'un consentement de paiement est créé avec succès par Moneris, la réponse renvoie les valeurs consentId, correlationId ainsi que les données de transaction du consentement. Cette charge utile de réponse doit être passée à konekClient au moyen de la méthode setConsentData.

Cela amorce le processus de paiement en lançant l'application KONEK, où les étapes restantes sont complétées. Pendant ce temps, une superposition est affichée sur le site du commerçant avec un message d'état. Enfin, lorsque le paiement est complété ou en cas d'échec, les événements appropriés sont distribués par le konek-button-v1.

📘
Gestion des erreurs de création de consentement
En cas d'erreur, createConsentFailed doit être transmis à konekClient au moyen de la méthode setConsentError afin que le message approprié s'affiche dans la superposition.

Configurer un écouteur d'événement pour konekSuccess

Le konek-button distribue un événement konekSuccess lorsque KONEK est chargé avec succès, puis à nouveau lorsque le processus de paiement est complété et que le consentement obtient le statut « Tokenized ». Un écouteur d'événement doit être attaché pour gérer les étapes suivantes.

konek.addEventListener('konekSuccess', event => {
  console.log(event.detail);
  // Continue to order review or payment confirmation
});

Codes d'événement

Code d'événement (`event.detail`)	Description
konekLoaded	KONEK est chargé avec succès.
konekCompleted	Le processus de paiement est complété. Le statut du consentement est « Tokenized ».

Pour obtenir les renseignements de paiement, le commerçant doit appeler l'API Retrieve KONEK Payment Consent.
Selon le mode d'affichage (placementMode) sélectionné lors de la création du consentement de paiement KONEK par le commerçant (Standard ou Express), la situation est gérée de l'une des deux façons suivantes :
1. Standard : après avoir complété le processus KONEK, les commerçants doivent afficher une page intermédiaire présentant au client les détails du paiement et lui demandant d'examiner et de confirmer sa commande pour compléter le paiement. Ce processus est illustré à la figure: Mode de placement Standard.
2. Express : après avoir complété le processus KONEK, les commerçants doivent soumettre l'autorisation et afficher une page « paiement complété » avec l'état de la transaction et le reçu électronique. Ce processus est illustré à la figure: Mode de placement Express.
Finalisez la commande auprès de l'acquéreur à l'aide des données de transaction.

konek15

konek2

French_checkout_payment_review_screen_updated

konek4

Mode de placement Standard

Mode de placement Express

Configurer un écouteur d'événement pour konekError

Toute erreur survenant durant le processus de paiement déclenche un événement konekError sur le bouton KONEK. Un écouteur d'événement doit être attaché pour gérer les différents scénarios d'erreur. Les détails concernant l'erreur sont accessibles dans la propriété detail de l'objet événement (voir le tableau Codes d'erreur).

konek.addEventListener('konekError', event => {
  console.log(event.detail);
  // Handle error scenarios
});

Références pour les objets KONEK

Propriétés du bouton KONEK

Propriété	Description	Valeur par défaut	Type de données
client	Objet `konekClient`. Il est requis pour déclencher l'événement amorçant le processus de paiement. (Peut être utilisé à des fins de débogage.)	S.O.	konekClient
border-radius	Propriété CSS	4	Number
width	Propriété CSS	Auto	Number
height	Propriété CSS	32	Number
color	Couleur du bouton	Black	White / Black

Événements du bouton KONEK

Événement	Description	Codes d'événement (`event.detail`)
konekInit	Distribué lorsque le bouton et le client sont entièrement chargés et prêts à recevoir les données de jeton.	—
konekSuccess	Distribué au lancement réussi de KONEK, à la fin du processus de paiement et lorsque le consentement est tokenisé.	`konekLoaded`, `konekCompleted`
konekError	Distribué lorsqu'une erreur ou un avertissement survient durant le processus de paiement. Une description complète de chaque événement se trouve dans le tableau: Codes d'erreur.	`consentPayloadError`, `createConsentFailed`, `popupBlocked`, `konekLoadError`, `konekError`, `konekClosed`, `konekCancelled`, `konekWarning`, `konekHeartBeat`

Codes d'erreur

Code d'erreur (`event.detail`)	Description
`createConsentFailed`	L'appel à l'API de création de consentement a échoué depuis les systèmes back-end du commerçant.
`popupBlocked`	Une fenêtre contextuelle a été bloquée par le navigateur ou l'appareil de l'utilisateur.
`konekLoadError`	Échec du chargement de KONEK.
`konekCancelled`	L'utilisateur a annulé une session KONEK en cliquant activement sur le bouton « Fermer et retourner au commerçant ».
`konekClosed`	La fenêtre KONEK a été fermée par l'utilisateur.
`konekError`	Erreur irrécupérable dans KONEK.
`konekWarning`	Avertissement provenant de KONEK. L'utilisateur peut continuer ou réessayer de compléter le processus de paiement.
`konekHeartBeat`	Signal « heartbeat » envoyé par le SDK du commerçant à KONEK ainsi que son accusé de réception.

API Moneris KONEK

Créer le consentement de paiement Konek

Lors de la première phase, le titulaire de la carte passe sa commande sur le site Web du commerçant et sélectionne KONEK comme mode de paiement. Le serveur du commerçant utilise l'appel à l'API Moneris Create KONEK Payment Consent pour obtenir un paymentConsentid KONEK. L'API Moneris communique avec KONEK au nom du commerçant et transmet les détails de la commande à Interac.

Ce paymentConsentid est utilisé au sein du SDK KONEK pour garantir que seuls les commerçants authentifiés peuvent afficher l'invite d'ouverture de session pour la fenêtre KONEK. Cet appel fournit également à l'API Moneris et à KONEK les détails de paiement de la commande, les modes de paiement pris en charge par le commerçant ainsi que les coordonnées requises du titulaire de la carte.

Lors de la deuxième phase, le site Web du commerçant amorce le SDK JavaScript de KONEK. Cela appelle les systèmes KONEK afin d'afficher une page de connexion pour l'utilisateur. Le titulaire de la carte saisit les identifiants de son institution financière (IF) pour se connecter à KONEK. L'interface utilisateur affiche les modes de paiement disponibles associés à son profil pour la sélection, incluant à la fois les produits de carte de crédit et les comptes bancaires. Le titulaire de la carte accorde son consentement au mode de paiement au sein de l'interface utilisateur, ce qui est communiqué en retour au système KONEK. Le site Web du commerçant reçoit un message POST avec l'état du consentement et de la commande.

📘
Veuillez noter:
La deuxième phase décrit l'interaction utilisateur qui suit l'appel à l'API ci-dessus, mais n'est pas elle-même un appel à l'API.
Votre serveur n'effectue pas d'appel à Moneris durant cette phase. Le SDK KONEK et les systèmes KONEK gèrent directement l'interaction avec le client.

Récupérer le consentement

La troisième phase débute lorsque le titulaire de la carte examine sa commande sur le site Web du commerçant. Le serveur du commerçant envoie un appel à l'API Retrieve KONEK Payment Consent, avec le paymentConsentid de la première étape (voir la section Créer le consentement de paiement Konek), à l'API Moneris afin de valider le consentement de paiement. L'API Moneris interagit avec KONEK pour retourner les données liées au consentement obtenu dans la fenêtre KONEK. Le site Web du commerçant peut réafficher les détails de la commande obtenus à partir de cet appel dans le cadre de la confirmation du paiement par le titulaire de la carte.

Traiter la transaction financière

Le commerçant peut procéder au traitement d'une transaction financière comme un achat ou une préautorisation en utilisant l'API Create Payment avec Konek Payment.

Paiements basés sur le compte: Utilisez le jeton de paiement et le cryptogramme fournis avec le consentement pour traiter un achat ou une préautorisation via l'API Moneris. Complétez la requête avec les données de l'authentification Pay By Bank (PBB). Consultez la spécification de l'API Moneris pour le schéma complet de la requête.
Paiements par carte: Pour les paiements par carte, complétez la transaction financière en utilisant les points de terminaison standard de l'API Moneris, en suivant les règles de chaque réseau de cartes. Les paiements par carte initiés par KONEK peuvent nécessiter des champs nouveaux ou mis à jour dans la demande d'autorisation — consultez la spécification de l'API Moneris pour la liste complète.

📘
Afficher les quatre derniers chiffres lors de la confirmation
Moneris recommande aux développeurs de récupérer les quatre derniers chiffres du numéro de compte bancaire ou du numéro de carte de crédit (PAN) utilisé comme mode de paiement tokenisé. Le commerçant peut afficher ces chiffres au client dans le cadre du processus de confirmation de la commande pour rassurer le titulaire de la carte que son mode de paiement correspond à sa sélection dans l'interface KONEK.

📘
Apprenez-en davantage sur les réponses avec le lien ci-dessous
Accéder à la gestion des réponse

Directives de test pour les commerçants

Obtenir des identifiants de test

Les commerçants doivent communiquer avec leur conseiller-client Moneris pour activer KONEK sur leur profil de commerce API Moneris avant de procéder aux tests. Pour les utilisateurs de test KONEK dans l'environnement de certification, l'IF de test et les identifiants de l'utilisateur de test sont inclus dans cette section. Plusieurs identifiants de test sont requis pour les commerçants Moneris testant KONEK. Un résumé de ces identifiants figure dans le tableau Résumé des identifiants de test KONEK. Une description de chaque identifiant et des captures d'écran illustrant leur emplacement dans le processus d'interface utilisateur sont incluses dans cette section.

Résumé des identifiants de test KONEK

Nom de l'identifiant de test	Valeur	Voir
ID de commerçant KONEK (MID)	CAMX001001	S.O.
Code d'accès	skipme	Figure: Code d'accès pour le test KONEK
Nom de l'IF de test	Polar Bank	Figure 4: IF de test pour le test KONEK
Identifiants de l'utilisateur de test	–	La liste à puces ci-dessous

Lors des tests de l'interface utilisateur KONEK, les identifiants suivants sont requis :

Nom d'utilisateur : monerisuser
Mot de passe : Moneris1!
Courriel : [email protected]

Tous les commerçants dans l'environnement de certification Moneris peuvent utiliser le même MID KONEK, indiqué dans le tableau Résumé des identifiants de test KONEK. Ce MID KONEK est requis pour la communication à l'API KONEK.

De plus, le test KONEK nécessite une simulation du système bancaire dans le processus d'interface utilisateur. Les commerçants doivent utiliser l'IF de test « Polar Bank » lors des tests KONEK, tel qu'illustré à la figure: Code d'accès pour le test KONEK. Les commerçants auront besoin des identifiants de l'utilisateur de test qui se trouvent dans le tableau: Résumé des identifiants de test KONEK. La figure: Saisie des identifiants de l'utilisateur de test dans Polar Bank montre un exemple d'identifiants d'utilisateur de test entrés sur la page de test Polar Bank.

konek13

konek7

Code d'accès pour le test KONEK

IF de test pour le test KONEK

Saisie des identifiants de l'utilisateur de test dans Polar Bank

Tests KONEK

Les scénarios de test KONEK recommandés par Moneris sont contenus dans un document distinct qui sera fourni par le conseiller-client du commerçant. Il s'agit d'une trousse d'autotest que les commerçants devraient parcourir en effectuant les tests appropriés selon les besoins de leur entreprise. Il est recommandé de conserver les preuves des tests si elles sont demandées plus tard à des fins d'audit. Cela doit s'aligner avec les responsabilités du commerçant selon KONEK et Interac Direct ainsi qu'avec leurs modalités et conditions commerciales.

📘
Scénarios de test et soutien
Moneris fournit une trousse d'autotest KONEK distincte par l'entremise de votre conseiller-client. Exécutez les scénarios qui correspondent aux besoins de votre entreprise et conservez les preuves des tests au cas où elles seraient requises à des fins d'audit. Pour obtenir du soutien durant les tests, communiquez avec votre conseiller-client.

Passage à la production

Lorsque la solution est prête à être déployée du test à la production, le processus d'intégration s'effectuera pour KONEK et Interac Direct.

L'option de paiement KONEK et le plan de carte Interac Direct seront activés dans le profil de commerce API Moneris. Les commerçants doivent communiquer avec leur équipe des ventes ou leur gestionnaire de compte pour l'intégration à KONEK et Interac Direct.
Lors du passage à la production, les commerçants doivent remplacer l'URL du SDK de test décrite à la section Importer le SDK par celle de production :

<script type="module" src="https://sdk.konek.ca/konek-sdk/konek-sdk.esm.js"></script>

Les commerçants doivent également utiliser leur ID de commerçant KONEK de production (qui est fourni au moment de l'intégration).

Renseignements supplémentaires

📘
Définitions de l'API
Consultez les endpoints (points de terminaison), les formats des demandes et des réponses, ainsi que les modes d'authentification de ce scénario.
Définitions de l'API