PrestaShop

Le module Wajub ajoute trois moyens de paiement à une boutique PrestaShop 8.1 ou 9 : Mobile Money et Carte bancaire, chacun avec le formulaire de paiement de Wajub dans le tunnel de commande, et Autres moyens de paiement, qui envoie le payeur sur la page de paiement Wajub pour tout ce que votre compte propose d'autre. Il crée la commande quand le client la passe, la règle avec le webhook de Wajub et la rembourse dans les deux sens. Un paiement compte pour ce qu'il a encaissé, le client paie le reste, et la sandbox et le live ne se mélangent jamais.

Le module est traduit en français : cette page reprend les libellés de son administration en français, où la sandbox s'appelle « Test » et le live « Production ».

Prérequis

Le module n'a aucune dépendance : son client de l'API est le sien, et le zip ne contient rien d'autre.

Installer le module

1. 1

   Téléverser le zip

   Dans le back-office, Modules, Gestionnaire de modules, Installer un module, puis choisissez wajub.zip, depuis PrestaShop Addons ou depuis Wajub. Le zip contient un seul dossier, wajub/.

2. 2

   Ouvrir ses réglages

   Configurer ouvre la page du module, en quatre onglets : Connexion, Moyens de paiement, Apparence et Webhooks. PrestaShop donne cette page au SuperAdmin et au profil de l'employé qui a installé le module ; Paramètres avancés, Équipe, Permissions la donne aux autres, sous Paiement, Wajub.

3. 3

   Connecter, puis tester

   Connectez la boutique à votre compte (ci-dessous), passez une commande de test, puis passez en Production.

Le module ajoute deux états de commande, En attente de paiement Wajub et Partiellement payée avec Wajub. Une commande payée en entier passe à l'état Paiement accepté de PrestaShop.

Connecter votre compte Wajub

La boutique a besoin d'une clé secrète par environnement. Laissez Wajub la créer avec Connexion avec Wajub, ou collez la vôtre.

Connexion avec Wajub

Cliquez sur Connecter en mode Test ou Connecter en production (Reconnecter une fois une clé enregistrée) dans l'onglet Connexion. La boutique affiche un code et ouvre la page d'approbation du Dashboard dans un nouvel onglet : vérifiez que le code est le même, choisissez l'environnement, un accès complet ou une clé restreinte (les permissions dont le module a besoin, paiements, remboursements et webhooks, sont cochées), et la durée de la clé, 90 jours ou Durée indéterminée, puis cliquez sur Autoriser. La boutique récupère la clé une seule fois, la contrôle comme une clé collée, l'enregistre chiffrée et enregistre le webhook avec elle. La clé n'atteint jamais le navigateur.

Pour se connecter, la boutique envoie au Dashboard son nom et son domaine, l'environnement demandé, le type de client prestashop, une empreinte de son adresse et les permissions dont elle a besoin. Toute application peut utiliser le même échange : voir Connecter votre application à Wajub.

Expiration d'une clé connectée

Une clé de 90 jours cesse de fonctionner à sa date, que l'onglet Connexion affiche. À partir de 14 jours avant :

• chaque page du back-office affiche Votre clé Wajub expire bientôt., puis Votre clé Wajub a expiré., aux employés qui peuvent modifier les réglages du module, pour la clé avec laquelle chaque boutique paie, avec un lien pour se reconnecter (voir Alertes du back-office) ;
• l'adresse e-mail de la boutique (Paramètres de la boutique, Contact) reçoit un e-mail par clé, sandbox ou live, dans la langue par défaut de la boutique. La tâche planifiée du module l'envoie, ou la première page du back-office qui affiche l'alerte. Une copie de la boutique à une autre adresse n'en envoie pas.

Choisissez Durée indéterminée pour une boutique dont le paiement ne doit pas s'arrêter.

Coller vos clés

Ouvrez Coller plutôt vos clés dans l'onglet Connexion, et collez les clés du Dashboard : sk_test. ou rk_test. pour la sandbox, sk. ou rk. pour le live. Chaque clé est vérifiée auprès de Wajub avant d'être enregistrée, et la page n'en montre ensuite que les derniers caractères. Une clé live collée dans le champ de test est refusée.

Sandbox et live

Chaque environnement paie avec sa seule clé. En Test sans clé de test, la boutique n'accepte aucun paiement, même avec une clé live enregistrée, et l'onglet Connexion le dit. Le module refuse de passer en Production sans clé live, demande de confirmer avant de le faire, et garde la clé live tant que Production est choisi.

Un paiement est lu, annulé et remboursé avec la clé de l'environnement où il a été fait, quel que soit l'environnement que la boutique utilise maintenant. Le remboursement d'une commande payée dans l'autre environnement est refusé.

Tant que la boutique accepte des paiements de test, l'en-tête de chaque page du back-office affiche Wajub · Test, un lien vers l'onglet Connexion, aux employés qui ont accès aux réglages du module. Sur une boutique ouverte au public (mode debug désactivé) qui accepte encore des paiements de test, le back-office affiche aussi Wajub est en mode Test. : voir Alertes du back-office.

Enregistrer le webhook

Configurer automatiquement, dans l'onglet Webhooks, trouve ou crée l'endpoint de la boutique dans votre compte Wajub, l'abonne aux événements ci-dessous et enregistre son secret de signature. Un endpoint qui a déjà l'adresse de la boutique est gardé, et reçoit les événements qui lui manquent. Obtenir un nouveau secret de signature renouvelle le secret. Connexion avec Wajub enregistre aussi l'endpoint. Quand une mise à jour du module écoute de nouveaux événements, elle les ajoute à l'endpoint que la boutique a enregistré, et garde les autres.

Le catalogue des événements décrit chacun d'eux.

L'onglet affiche l'adresse du webhook de la boutique, https://example.com/module/wajub/webhook (ou index.php?fc=module&module=wajub&controller=webhook sans URL simplifiées), la dernière notification acceptée et, quand des notifications sont refusées, pourquoi et quoi faire. Pour le configurer à la main, ajoutez cette adresse dans le Dashboard, Développeurs, Webhooks, avec les événements ci-dessus, et collez son secret de signature dans l'onglet.

Wajub ne peut pas joindre une boutique installée sur votre ordinateur : testez-la avec wajub listen --forward-to et l'adresse du webhook de la boutique, depuis la CLI. Les webhooks live demandent une adresse en https://.

Le tunnel de commande

Mobile Money et carte bancaire

Chaque moyen affiche le formulaire de paiement de Wajub dans son bloc, avec la police, les couleurs et les arrondis de votre thème. Apparence, Formulaire de paiement, impose un formulaire clair ou sombre. Un payeur Mobile Money saisit le numéro avec lequel il paie et choisit son opérateur dans une liste avec son logo, l'opérateur du numéro déjà choisi (un réglage de l'onglet Moyens de paiement le déduit plutôt du numéro), puis approuve le paiement sur son téléphone. Un payeur par carte saisit sa carte, avec 3-D Secure quand la banque le demande.

Dès qu'un moyen est choisi, la boutique prépare un paiement pour le panier, avant que la commande n'existe : le montant, la devise, le type du moyen et le panier, rien sur le payeur. Commander crée la commande, puis active ce paiement pour elle, avec le nom, l'adresse e-mail et le téléphone du payeur. Un paiement préparé jamais activé n'est débité à personne, et expire.

Sans JavaScript, ou si le formulaire ne se charge pas en 15 secondes, le payeur paie sur la page de paiement Wajub, qui ne propose alors que le type de ce moyen.

Autres moyens de paiement

Le payeur va sur la page de paiement Wajub, qui ne propose que ce que votre compte a en plus du Mobile Money et de la carte : PayPal, portefeuilles et autres. Le moyen ne s'affiche que s'il en reste.

Chaque moyen ne s'affiche que si votre compte le propose pour la devise, le total et le pays du panier (GET /payments/options, gardé 10 minutes, ou 1 minute quand Wajub ne répond pas). Quand Wajub ne répond pas, Mobile Money et Carte bancaire s'affichent, et Autres moyens de paiement non.

Passer la commande

La commande est créée quand le client la passe, dans l'état En attente de paiement Wajub. Son e-mail de confirmation attend qu'elle soit payée. Tant qu'un paiement Mobile Money attend l'approbation du payeur, la page de confirmation de commande dit quoi faire sur le téléphone, suit le paiement et se met à jour seule.

Un paiement refusé, annulé ou expiré, ou Choisir un autre moyen de paiement, annule la commande et rend le panier, avec un message, sauf si un paiement de la commande peut encore aboutir.

Quand un paiement ne couvre pas la commande

Un paiement compte pour sa commande à hauteur de ce qu'il a encaissé. Un paiement qui couvre le total paie la commande ; un paiement qui n'y suffit pas (paiement échelonné clos plus tôt, commande modifiée après le début du paiement) la fait passer à Partiellement payée avec Wajub, et le client paie le reste avec Payer le reste, sur la page de confirmation de commande et dans Détails de la commande de son compte. Le nouveau paiement, nommé d'après la commande (Order #XKBKNABJK-2), ne demande que ce qui reste. Un paiement échelonné encore ouvert est repris quand c'est possible, ou clos en gardant ce qu'il a encaissé.

Le marchand lit sur la commande quand un second paiement a abouti, ou un paiement dans une autre devise.

Modules de commande en une page

Le module est testé avec le tunnel de commande de PrestaShop. Un module de commande en une page redessine les moyens de paiement après chaque changement d'adresse ou de transporteur, et a son propre bouton ; le module s'en accommode tant que les moyens gardent le balisage de PrestaShop :

• chaque moyen garde son bouton radio name="payment-option", et le bloc Wajub ([data-wajub-fields]) et le formulaire (form[data-wajub-form]) restent dans le bloc de leur moyen ;
• le module surveille la page : quand les moyens sont redessinés, le formulaire est remonté, sur le même paiement préparé. Un module peut aussi appeler window.WajubCheckout.sync() après les avoir redessinés ;
• tout ce qui soumet le formulaire d'un moyen Wajub, le bouton Commander de PrestaShop, le bouton d'un module, ou un script qui appelle submit(), passe par les mêmes étapes.

Quand rien de cela ne tient, le payeur paie sur la page de paiement Wajub, et la commande est passée quand même.

Les commandes dans le back-office

Le bloc Paiement Wajub d'une commande liste ses paiements (statut, moyen, montant, ce qui a compté, environnement, un lien vers le Dashboard), ses remboursements et les notes du module. Vérifier le statut lit le paiement chez Wajub et règle la commande comme le ferait le webhook, pour une commande qui attend encore son paiement.

Commandes livrées en plusieurs colis

Quand les produits d'un panier partent avec des transporteurs différents, PrestaShop divise la commande en plusieurs commandes sous une même référence. Le module les traite comme une seule : un paiement Wajub pour leur total, Payer le reste et Vérifier le statut depuis l'une ou l'autre, un remboursement de l'une ou l'autre rendu par leurs paiements, une seule suite de notes, et une commande impayée annulée avec toutes les autres. Le bloc Paiement Wajub de chaque commande, et la ligne du client qui dit ce qui reste à payer, précisent que leurs montants valent pour l'ensemble des commandes de la référence. Un remboursement fait dans le Dashboard devient un avoir par commande, chacun jusqu'au total de sa commande.

Un paiement qui ne peut pas encore compter

Un paiement qui a abouti, mais dont les remboursements n'ont pas pu être lus à ce moment-là, ne compte pas encore pour sa commande : la commande reste telle quelle, n'est jamais annulée comme impayée à cause de lui, et son bloc Paiement Wajub le dit. La boutique relit le paiement environ cinq minutes plus tard, depuis les pages suivantes de la boutique ou du back-office, sans attendre la tâche planifiée, puis de nouveau plus tard tant qu'il ne peut toujours pas compter. La tâche planifiée, et l'ouverture de la commande dans le back-office, le relisent aussi. Il n'y a rien à configurer.

Remboursements

Un remboursement fait depuis la page de la commande, avec Remboursement partiel, Remboursement standard ou Retourner les produits, est remboursé par Wajub avant que PrestaShop ne crée son avoir, du montant que cet avoir rend, taxes comprises, y compris pour un client dont le groupe voit les prix hors taxes. Le paiement fait en dernier est remboursé en premier.

Un remboursement que Wajub ou le module refuse (plus que ce que les paiements de la commande détiennent, commande payée dans l'autre environnement ou jamais payée en entier) ne crée pas d'avoir, mode debug activé ou non, et la page de la commande dit pourquoi. Quand Wajub rembourse une part puis refuse le reste, la part remboursée reçoit un avoir à elle, et n'est jamais remboursée deux fois. Un remboursement en bon de réduction ne rend pas d'argent : rien ne part chez Wajub.

Le module rembourse après les autres modules branchés sur les formulaires de remboursement, même ceux installés après lui, pour que chacun d'eux puisse refuser le remboursement avant lui. Quand l'erreur d'un autre module arrête PrestaShop une fois l'avoir créé, l'avoir enregistre quand même ce que Wajub a remboursé, et une note sur la commande vous demande de vérifier les quantités remboursées des produits.

Un remboursement fait dans le Dashboard est enregistré sur la commande comme un avoir. Le remboursement de tout ce que la commande a payé la fait passer à Remboursé.

Commandes impayées et tâche planifiée

Une commande restée En attente de paiement Wajub est annulée après le délai choisi dans l'onglet Moyens de paiement (60 minutes par défaut, 0 pour jamais), ses produits remis en stock, sauf si un de ses paiements peut encore aboutir ou si Wajub détient de l'argent pour elle. La même tâche relit les paiements qui n'ont pas encore pu compter, et envoie les e-mails d'expiration.

Le module Gestionnaire de tâches cron de PrestaShop la lance toutes les heures. Sans lui, faites appeler par le cron de votre hébergeur, toutes les 15 minutes, l'adresse affichée dans l'onglet Moyens de paiement : Copier la copie. Elle contient un jeton : gardez-la privée. L'onglet dit quand la tâche s'est exécutée pour la dernière fois, et le back-office prévient quand elle ne s'est pas exécutée depuis trois heures.

Alertes du back-office

Le module signale aux employés qui peuvent modifier ses réglages ce qui demande leur attention, sur les pages où cela compte, pour la boutique choisie dans le sélecteur de boutique. Il ne lit que ce qui est enregistré : une page du back-office n'attend jamais Wajub.

Les alertes mènent à ce qui les corrige ; celle de la tâche planifiée dit comment la lancer, et donne son adresse à copier. Masquer pendant 7 jours masque une alerte pour l'employé qui clique, et elle revient ensuite si ce dont elle prévient n'a pas changé.

Multiboutique

Chaque boutique, chaque groupe de boutiques, ou Toutes les boutiques, peut avoir sa propre connexion : environnement, clés et webhook. Le sélecteur de boutique du back-office choisit ce que la page règle, la page le dit, et l'onglet Connexion dit d'où vient chaque clé. Une boutique qui s'est connectée seule revient à la connexion partagée avec Utiliser la connexion enregistrée pour Toutes les boutiques.

Chaque portée qui enregistre un webhook a son propre endpoint, dont l'adresse la nomme (…/module/wajub/webhook?scope=s2), avec son propre secret de signature. Une commande est réglée avec les réglages de sa propre boutique, quelle que soit l'adresse par laquelle la notification est arrivée.

Données personnelles

Le module garde les paiements Wajub de chaque commande (identifiants, montants, statut, moyen, environnement, l'identifiant du client), leurs remboursements et leurs notes, et l'e-mail de confirmation d'une commande jusqu'à son paiement. Il ne garde ni nom, ni adresse e-mail, ni numéro de téléphone, ni carte. Avec le module RGPD de PrestaShop, l'export des données d'un client contient ses paiements Wajub, et l'effacement d'un client supprime les e-mails retenus et détache ses paiements, qui restent comme trace de l'argent des commandes.

Désinstaller le module

La désinstallation, ou Réinitialiser dans le gestionnaire de modules, supprime les réglages du module, ses clés et ses secrets de signature, et les e-mails de confirmation qu'il retenait. Elle garde vos commandes, leurs paiements, et la trace de leurs paiements, remboursements et notes Wajub, dans trois tables : wajub_payment, wajub_refund et wajub_order_note, avec le préfixe des tables de votre boutique (ps_wajub_payment par défaut). La confirmation que PrestaShop demande avant de désinstaller les nomme. Une nouvelle installation retrouve cette trace.

Pour effacer aussi cette trace, supprimez les trois tables après la désinstallation. Les commandes et leurs paiements PrestaShop restent, mais une nouvelle installation ne sait plus quels paiements Wajub les ont payées, et ne peut plus les rembourser par Wajub depuis la page de la commande.

Les clés créées par Connexion avec Wajub et les endpoints de webhook restent dans votre compte Wajub : supprimez-les depuis le Dashboard, Développeurs.

Dépannage