VibeFox Pesapal for WooCommerce — Aide

Prérequis

WordPress: 6.2 ou ultérieur.

WooCommerce: 8.0 ou ultérieur, installé et actif. L’extension refuse de s’activer sans WooCommerce.

PHP: 8.0 ou ultérieur.

Currency: la commande doit être en KES, UGX, TZS, ZMW, RWF ou USD. Pour les autres devises, le moyen de paiement est masqué sur la page de paiement. La commande est débitée dans sa propre devise ; l’extension ne convertit pas les devises. Les montants sont envoyés en unités principales, arrondis à la précision de la devise (UGX et RWF sans décimales).

Pesapal account: 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 : l’extension enregistre elle-même son URL de notification. Votre site doit être accessible depuis Internet, car Pesapal y envoie les notifications de paiement.

VibeFox license key: achetée sur vibefox.net. Une clé fonctionne sur un domaine.

Installation

1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l’extension et cliquez sur Install Now. Vous pouvez aussi transférer le dossier wcp_pesapal_pay vers /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Pesapal > Manage, ou cliquez sur Settings sous le nom de l’extension sur la page des extensions.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Saisissez la clé et le secret consommateur sandbox, activez Enable/Disable, enregistrez et passez une commande de test.

6. Saisissez la clé et le secret consommateur de production, décochez Sandbox mode et enregistrez pour accepter de vrais paiements.

Configuration

Tous les réglages se trouvent sur une page : WooCommerce > Settings > Payments > Pesapal. Au-dessus des champs, un badge indique le mode : SANDBOX avec Test payments on cybqa.pesapal.com — no real money is charged. ou LIVE avec Real payments on pay.pesapal.com. Un avertissement apparaît lorsque les clés du mode actuel manquent (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout., ou l’équivalent pour la production) et lorsque Pesapal ne prend pas en charge la devise de votre boutique. Dans la liste des moyens de paiement, Pesapal est indiqué en mode test lorsque sandbox est activé.

Notifications de paiement (IPN)

Ce bloc affiche l’URL de notification de votre boutique. Elle ressemble à https://your-site/wc-api/pesapal_pay/. L’URL est enregistrée automatiquement auprès de Pesapal au premier paiement, séparément pour sandbox et production et pour chaque paire de clés ; vous n’avez donc rien à configurer. Après le premier paiement, le bloc affiche Registered IPN ID: avec l’identifiant renvoyé par Pesapal ; auparavant, il indique Not registered yet for the current mode and keys. L’URL doit être accessible depuis Internet : sans mode maintenance, pare-feu ni protection par mot de passe qui en bloque l’accès.

Paiement

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

Title: le nom du moyen de paiement présenté aux clients sur la page de paiement. Par défaut : Pesapal (M-Pesa, Airtel Money, cards).

Description: le texte affiché sous le moyen de paiement sur la page de 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

La section explique où obtenir les clés et contient des liens vers cybqa.pesapal.com et pesapal.com. Saisissez les clés sandbox et production chacune dans son champ. Tous les champs de clés sont des champs de mot de passe.

Sandbox mode: Use the Pesapal sandbox (no real money). Lorsque cette option est activée, les nouveaux paiements utilisent cybqa.pesapal.com avec les clés sandbox. Décochez-la pour accepter de vrais paiements 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émonstration). 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é.

Le changement de mode ou de clés ne réutilise jamais un jeton d’accès ou 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.

Réglages avancés

Debug log: Log Pesapal requests and notifications écrit les détails dans WooCommerce > Status > Logs, source wcp_pesapal_pay. Les erreurs et avertissements sont toujours consignés. Les clés, jetons et données clients ne le sont jamais. Par défaut : désactivé.

Delete data: Delete the plugin settings and logs when the plugin is deleted. Les données Pesapal enregistrées dans les commandes (identifiants de suivi, notes) constituent l’historique des paiements et sont toujours conservées. La désactivation de l’extension ne supprime jamais rien. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Pesapal (M-Pesa, Airtel Money, cards)) et passe commande. En mode sandbox, le bloc Paiement affiche Sandbox mode: no real money will be charged. L’extension crée une demande de paiement Pesapal pour le total de la commande dans sa devise, avec ses coordonnées de facturation, et ajoute une note de commande avec le mode, le montant et l’identifiant de suivi Pesapal. Le client est redirigé vers la page de paiement Pesapal et paie avec l’un des moyens proposés par Pesapal, comme M-Pesa, Airtel Money, MTN, par carte ou par banque.

La commande n’est marquée payée qu’après confirmation de Pesapal. Les notifications Pesapal et le retour du client ne contiennent ni données de paiement ni signature ; l’extension ne leur fait donc pas confiance : pour chacun, elle demande à Pesapal le statut de la transaction par une requête authentifiée entre serveurs, dans le mode où le paiement a été lancé. Elle vérifie aussi que la transaction appartient à cette commande et que le montant payé et la devise correspondent à la commande.

Après le paiement, le client revient sur la page de commande reçue. Les paiements par argent mobile peuvent prendre un moment. Si le paiement n’est pas encore confirmé, la page 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. La notification de Pesapal termine la commande ultérieurement. Si la commande a été mise en attente, la page 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 sur la page Pay for order avec 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 client peut payer à nouveau la même commande. Chaque tentative de paiement est conservée, de sorte qu’un paiement effectué plus tard sur une ancienne page Pesapal de la commande est également accepté.

Si Pesapal ne peut pas lancer le paiement, le client voit 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 du motif fourni par Pesapal. Les détails techniques figurent dans les notes de commande et le journal. Le total de la commande doit être supérieur à zéro.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec le stockage haute performance des commandes WooCommerce (HPOS).

L’extension ne propose ni formulaire de paiement sur la page de paiement elle-même (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 des commandes

Pending payment: le client a été redirigé vers Pesapal et n’a pas encore payé, ou Pesapal n’a pas encore confirmé le paiement.

Processing: Pesapal indique que le paiement est terminé et le montant et la devise correspondent. La note de commande affiche le montant, le moyen de paiement, le code de confirmation Pesapal et l’identifiant de suivi. L’identifiant de transaction de la commande est l’identifiant de suivi Pesapal. Chaque paiement est appliqué une seule fois.

On hold: le montant payé ou la devise diffère de la commande (note Pesapal amount/currency mismatch — held for review), ou de l’argent est arrivé pour une commande annulée avant son paiement. Vérifiez le paiement dans le tableau de bord Pesapal, puis terminez la commande ou remboursez le paiement.

Failed: Pesapal signale l’échec de la dernière tentative de paiement. La note indique le motif fourni par Pesapal. Si le client réessaie depuis la page Pay for order et que cette tentative échoue aussi, une autre note avec le motif est ajoutée. L’échec d’une ancienne tentative ne modifie pas la commande. Le client peut payer à nouveau.

Refunded: Pesapal signale l’annulation du paiement ayant réglé la commande. L’annulation d’une autre tentative est seulement consignée dans la commande.

Si une seconde tentative de paiement d’une commande déjà payée aboutit également, la commande n’est pas modifiée. 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.

Remboursements

L’extension n’envoie pas de remboursements à Pesapal. Remboursez le paiement dans le tableau de bord Pesapal, puis enregistrez manuellement le remboursement dans WooCommerce.

Clé de licence

L’extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence est en haut de WooCommerce > Settings > Payments > Pesapal. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date de fin de validité de la licence et votre domaine. Utilisez Check now pour revérifier le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un domaine. Retirer la clé d’un site ne libère pas son emplacement de domaine. Libérez cet emplacement dans votre compte vibefox.net.

Sans clé active, Pesapal n’est pas présenté aux clients sur la page de paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), pour vous permettre de configurer et tester l’extension avant d’acheter une clé. Un rappel apparaît sur la page des extensions et les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés restent confirmés par la notification Pesapal et le retour du client.

À l’expiration d’une licence, l’extension continue de fonctionner, mais les mises à jour et l’assistance nécessitent un renouvellement. Le statut est revérifié automatiquement en arrière-plan.

Dépannage

Pesapal n’apparaît pas sur la page de paiement : vérifiez que la licence est active, que Enable/Disable est activé, que la clé et le secret consommateur du mode actuel sont renseignés (Sandbox consumer key et Sandbox consumer secret en mode sandbox, Live consumer key et Live consumer secret en production) et que la devise de la commande est KES, UGX, TZS, ZMW, RWF ou USD. Les avertissements en haut des réglages indiquent le problème. Les développeurs peuvent modifier la liste des devises avec le filtre pesapal_p_supported_currencies.

Le paiement a abouti, mais la commande reste En attente de paiement : la notification Pesapal n’est pas parvenue à votre boutique et le client n’est pas revenu. Vérifiez que l’URL affichée dans Payment notifications (IPN) est accessible depuis Internet (sans mode maintenance, pare-feu ni protection par mot de passe devant /wc-api/pesapal_pay/). Consultez WooCommerce > Status > Logs, source wcp_pesapal_pay.

Comment la boutique répond aux notifications : une notification traitée reçoit une réponse HTTP 200. Lorsque l’extension ne peut pas la traiter, elle répond par une erreur et Pesapal renvoie la notification plus tard : 400 (identifiant de suivi absent ou mal formé), 404 (aucune commande de cette boutique n’a cet identifiant de suivi), 409 (la transaction appartient à une autre référence marchand ; la commande n’est pas modifiée), 502 (l’API Pesapal était inaccessible à cet instant) et 503 (la commande était simultanément mise à jour par le retour du client).

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, celles de production uniquement en production. La note de commande affiche l’erreur Pesapal.

Le client voit Pesapal is temporarily unavailable : Pesapal était inaccessible ou l’URL de notification n’a pas pu être enregistrée. Lisez la note de commande et le journal, puis réessayez.

La commande est En attente après le paiement : lisez la note de commande. Le montant payé ou la devise différait de la commande, ou le paiement est arrivé après son annulation. Vérifiez le paiement dans le tableau de bord Pesapal, puis traitez la commande ou remboursez le paiement.

Le bloc de licence affiche une erreur : suivez le message du bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l’adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est inaccessible, l’extension continue avec le dernier statut connu.

Désinstallation

La désactivation de l’extension conserve toutes les données. Pour la retirer, désactivez-la et supprimez-la sur la page Plugins. La clé et le statut de licence de cette extension, les jetons d’accès Pesapal en cache et les identifiants de notification enregistrés sont toujours supprimés. Les réglages de l’extension et ses journaux (fichiers journaux, y compris ceux ayant subi une rotation, et entrées de journal en base de données de la source wcp_pesapal_pay) sont supprimés uniquement si Delete data était activé. Sinon, ils restent disponibles pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, identifiants de transaction et identifiants de suivi Pesapal.

Pesapal est une marque commerciale de son propriétaire respectif. Cette extension n’est ni affiliée à Pesapal ni approuvée par Pesapal.