VibeFox Pesapal for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s’installer sur les versions antérieures de PHP.

Devise : le panier doit être en KES, UGX, TZS, ZMW, RWF ou USD. Dans les autres devises, le moyen de paiement est masqué à l’étape du paiement. Le panier est débité dans sa propre devise ; le module ne convertit pas les devises. Les montants sont envoyés en unités principales, arrondis à la précision de la devise (sans décimales pour l’UGX et le RWF).

Compte Pesapal : vous avez besoin de la clé et du secret consommateur d’un compte marchand Pesapal. Les clés sandbox et production sont différentes. Les clés sandbox proviennent d’un compte marchand de démonstration sur cybqa.pesapal.com (Pesapal publie aussi des clés de démonstration sur son portail développeurs). Les clés de production proviennent de votre tableau de bord marchand Pesapal. Aucune autre configuration n’est nécessaire dans le tableau de bord Pesapal : le module enregistre lui-même son URL de notification. Votre boutique doit être accessible depuis Internet, car Pesapal lui envoie les notifications de paiement.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans le back-office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Pesapal Pay Gateway dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez la clé et le secret consommateur sandbox, activez Enable/Disable, cliquez sur Save et passez une commande de test.

5. Saisissez la clé et le secret consommateur de production, désactivez Sandbox mode et cliquez sur Save pour accepter des paiements réels.

À l’installation, le module crée le statut de commande Pesapal payment on hold. PrestaShop active le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez restreindre cette activation dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, un badge indique le mode : SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. ou LIVE — Real payments on pay.pesapal.com. Un avertissement apparaît lorsque les clés du mode actuel sont absentes (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout., ou la même phrase pour le mode live) et lorsque Pesapal ne prend pas en charge la devise par défaut de votre boutique.

Pesapal

Enable/Disable : Enable Pesapal active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement affiché aux clients à l’étape du paiement. C’est aussi le nom enregistré dans la commande. Par défaut : Pesapal (M-Pesa, Airtel Money, cards). Obligatoire : un titre vide n’est pas enregistré, l’ancien est conservé.

Description : le texte affiché sous le moyen de paiement à l’étape du paiement. Par défaut : Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

Identifiants API

Cette section explique où obtenir les clés et renvoie vers cybqa.pesapal.com et pesapal.com. Saisissez les clés sandbox et production chacune dans son propre champ.

Sandbox mode : Use the Pesapal sandbox (no real money). Lorsqu’il est activé, les nouveaux paiements utilisent cybqa.pesapal.com avec les clés sandbox. Désactivez-le pour accepter des paiements réels sur pay.pesapal.com avec les clés de production. Par défaut : activé.

Sandbox consumer key : la clé consommateur de votre compte marchand sandbox (démo). Utilisée uniquement en mode sandbox.

Sandbox consumer secret : le secret consommateur de votre compte marchand sandbox. Utilisé uniquement en mode sandbox.

Live consumer key : la clé consommateur de votre tableau de bord marchand Pesapal. Utilisée lorsque le mode sandbox est désactivé.

Live consumer secret : le secret consommateur de votre tableau de bord marchand Pesapal. Utilisé lorsque le mode sandbox est désactivé.

Les clés et secrets enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Clear saved consumer keys and secrets : cochez la case et cliquez sur Save pour supprimer les quatre clés et secrets enregistrés.

L’enregistrement des réglages supprime les jetons d’accès Pesapal mis en cache. Changer de mode ou de clés ne réutilise jamais un jeton d’accès ni un identifiant de notification de l’autre mode ou d’autres clés. Un paiement lancé dans un mode est toujours vérifié dans ce mode, même après un changement.

Notifications de paiement (IPN)

IPN URL : affiche l’URL de notification de votre boutique. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_pesapal_pay/webhook, éventuellement avec un code de langue comme /en/. L’URL est enregistrée automatiquement auprès de Pesapal lors du premier paiement, séparément pour le sandbox et la production et pour chaque couple de clés : il n’y a donc rien à configurer. Après le premier paiement, la section affiche Registered IPN ID: avec l’identifiant renvoyé par Pesapal ; avant cela, elle indique Not registered yet for the current mode and keys. L’URL doit être accessible depuis Internet : aucun pare-feu ni protection par mot de passe ne doit la bloquer. Elle reste active lorsque la boutique est en maintenance et n’est pas bloquée par la restriction géographique de votre boutique.

Avancé

Debug log : Log Pesapal requests and notifications. Écrit les détails dans logs/pesapal_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours journalisés, même lorsque l’option est désactivée. Les clés, les jetons et les données clients ne sont jamais journalisés. Par défaut : désactivé.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete data : Delete the module settings and logs when the module is uninstalled. Les données Pesapal enregistrées sur les commandes (identifiants de suivi, notes) font partie de l’historique des paiements et sont toujours conservées. Désactiver le module ne supprime rien. Par défaut : désactivé.

Paiement

À l’étape du paiement, le client choisit le moyen de paiement (par défaut Pesapal (M-Pesa, Airtel Money, cards)) et voit sa description. Après confirmation, le module crée une demande de paiement Pesapal pour le total du panier dans la devise du panier, avec les données de facturation de l’adresse de facturation, puis envoie le client sur la page de paiement Pesapal. La description du paiement transmise à Pesapal est Cart, suivi du numéro du panier et du nom de la boutique. Sur cette page, le client paie avec l’un des moyens proposés par Pesapal, comme M-Pesa, Airtel Money, MTN, carte ou virement bancaire. À ce stade, aucune commande n’existe encore.

La commande n’est marquée comme payée qu’après confirmation par Pesapal. Les notifications de Pesapal et le retour du client ne contiennent ni données de paiement ni signature : le module ne leur fait donc pas confiance. Pour chacun d’eux, il demande à Pesapal le statut de la transaction au moyen d’une requête authentifiée de serveur à serveur, dans le mode où le paiement a été lancé. Il vérifie aussi que la transaction appartient à ce panier et que le montant et la devise payés correspondent au panier. La commande est alors créée et le client voit la page standard de confirmation de commande.

Les paiements par argent mobile peuvent prendre un moment. Si Pesapal n’a pas encore confirmé le paiement lorsque le client revient, une page Payment confirmation affiche Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. avec les boutons Check again et Back to checkout. La notification de Pesapal crée la commande dès que le paiement est confirmé. Si la commande a été mise en attente, la page de confirmation affiche Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

Si le client annule sur la page Pesapal, il revient à l’étape du paiement avec le message The Pesapal payment was cancelled. You can try again or choose another payment method. Si le paiement échoue, le message est The Pesapal payment was not successful. Please try again or choose another payment method. Le panier est conservé et le client peut payer à nouveau. Chaque tentative de paiement du panier est mémorisée : un paiement effectué plus tard sur une ancienne page Pesapal du panier est donc accepté.

Si Pesapal ne parvient pas à lancer le paiement, le client reste à l’étape du paiement avec un bref message, par exemple Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method., Pesapal is not available at the moment. Please choose another payment method. (clés incorrectes) ou Pesapal could not start the payment: suivi de la raison donnée par Pesapal. La raison technique est écrite dans le journal. Le total de la commande doit être supérieur à zéro.

Le module ne propose aucun formulaire de paiement sur votre propre site (le client paie toujours sur la page Pesapal), ni cartes enregistrées, ni abonnements ou paiements récurrents, ni conversion de devises.

Commandes et remboursements

Statuts de commande

Aucune commande pour l’instant : le client a été envoyé vers Pesapal et n’a pas payé, le paiement a échoué, ou Pesapal n’a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : Pesapal signale le paiement comme terminé, et le montant et la devise correspondent. Le paiement est enregistré avec l’identifiant de suivi Pesapal comme identifiant de transaction, et une note indique le montant, le moyen de paiement, le code de confirmation Pesapal et l’identifiant de suivi. Chaque paiement n’est appliqué qu’une seule fois.

Pesapal payment on hold : le montant ou la devise payés diffèrent du panier (note Pesapal amount/currency mismatch — held for review), ou de l’argent est arrivé pour une commande qui avait été annulée. Le montant réellement payé est enregistré sur la commande lorsqu’il est dans la devise de la commande. Vérifiez le paiement dans le tableau de bord Pesapal, puis validez la commande ou remboursez le paiement.

Refunded : Pesapal signale que le paiement ayant réglé la commande a été annulé. L’annulation d’une autre tentative est seulement notée sur la commande.

Si une deuxième tentative de paiement d’un panier déjà payé aboutit également, la commande ne change pas. Une note vous demande de rembourser le second paiement dans le tableau de bord Pesapal. Les commandes annulées et remboursées ne sont jamais rouvertes automatiquement.

Bloc de paiement Pesapal

La page de commande affiche un bloc Pesapal payment avec un badge Sandbox ou Live, l’identifiant de suivi, la référence marchand, le statut Pesapal, le moyen de paiement, le code de confirmation, le montant demandé et le montant payé, le motif d’un examen, toutes les Payment attempts du panier et les Payment notes de la commande. Le bloc est en lecture seule.

Remboursements

Le module n’envoie pas de remboursements à Pesapal. Remboursez le paiement dans le tableau de bord Pesapal, puis enregistrez manuellement le remboursement dans PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Pesapal Pay Gateway est le premier bloc de Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu’à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-pesapal et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l’autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (l’anglais et le russe sont inclus).

Si la clé n’est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d’une date. Après un changement d’adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez cet emplacement dans votre compte vibefox.net.

Sans clé active, Pesapal n’est pas proposé aux clients à l’étape du paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office : le moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d’acheter une clé, mais vous ne pouvez pas le tester à l’étape du paiement. Un rappel apparaît dans Modules > Module Manager, sous l’onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés, et les notifications Pesapal concernant des paiements existants, y compris les annulations, sont toujours appliquées.

Lorsqu’une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n’est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.

Dépannage

Pesapal n’apparaît pas à l’étape du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que la clé et le secret consommateur du mode actuel sont saisis (Sandbox consumer key et Sandbox consumer secret en mode sandbox, Live consumer key et Live consumer secret en mode live) et que la devise du panier est KES, UGX, TZS, ZMW, RWF ou USD. Les avertissements en haut des réglages indiquent le problème. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client. Les développeurs peuvent modifier la liste des devises avec le hook actionPesapalSupportedCurrencies.

Le paiement a abouti, mais aucune commande n’a été créée : la notification de Pesapal n’a pas atteint votre boutique et le client n’est pas revenu. Vérifiez que l’URL affichée dans IPN URL est accessible depuis Internet (aucun pare-feu ni protection par mot de passe ne doit la bloquer). Activez Debug log et consultez le champ Log sur la page du module.

Comment la boutique répond aux notifications : une notification traitée reçoit une réponse HTTP 200. Si le module ne peut pas la traiter, il répond par une erreur, et Pesapal renvoie la notification plus tard : 400 (identifiant de suivi absent ou mal formé), 404 (aucun panier de cette boutique n’a cet identifiant de suivi), 409 (la transaction appartient à une autre référence marchand ; rien n’est modifié), 502 (l’API Pesapal n’a pas pu être jointe à ce moment, ou les clés du mode dans lequel le paiement a été lancé sont absentes) et 503 (le panier était en cours de mise à jour par le retour du client au même moment, ou la commande n’a pas pu être créée, par exemple parce que le module est désactivé).

Le client voit Pesapal is not available at the moment : Pesapal a rejeté la clé ou le secret consommateur du mode actuel. Vérifiez que les clés correspondent au mode : les clés sandbox ne fonctionnent qu’en sandbox, les clés de production uniquement en mode live. Le journal affiche l’erreur renvoyée par Pesapal.

Le client voit Pesapal is temporarily unavailable : Pesapal n’a pas pu être joint, ou l’URL de notification n’a pas pu être enregistrée. Consultez le journal et réessayez.

Les paiements d’un mode précédent ne sont pas confirmés après un changement : un paiement est vérifié avec les clés du mode dans lequel il a été lancé. Conservez les clés de ce mode tant que ses paiements ne sont pas confirmés.

La commande est en Pesapal payment on hold après le paiement : lisez les notes du bloc Pesapal payment. Le montant ou la devise payés différaient du panier, ou le paiement est arrivé après l’annulation de la commande. Vérifiez le paiement dans le tableau de bord Pesapal, puis traitez la commande ou remboursez le paiement.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Pesapal Pay Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Les jetons d’accès Pesapal mis en cache et les identifiants de notification enregistrés sont toujours supprimés. Si Delete data est activé, les réglages du module et le journal sont aussi supprimés. Sinon, tous les réglages sont conservés pour une réinstallation ultérieure. Les tentatives de paiement Pesapal et le statut de commande Pesapal payment on hold sont toujours conservés. Les commandes existantes gardent leurs notes de paiement, identifiants de transaction et identifiants de suivi Pesapal.

Pesapal est une marque de son propriétaire respectif. Ce module n’est ni affilié à Pesapal ni approuvé par Pesapal.