VibeFox Paymob for WooCommerce — Aide

Prérequis

WordPress : 6.2 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Compte Paymob : un compte marchand dans l'un des pays pris en charge : Égypte, Émirats arabes unis, Arabie saoudite, Oman ou Pakistan. Vous avez besoin de quatre valeurs du tableau de bord Paymob : la clé d'API, l'ID d'intégration d'une intégration de paiement en ligne, l'ID d'iFrame de la page de paiement et le secret HMAC.

Devise : la devise de la boutique doit être celle de votre pays Paymob : EGP pour l'Égypte, AED pour les Émirats arabes unis, SAR pour l'Arabie saoudite, OMR pour Oman, PKR pour le Pakistan. Avec une autre devise, le mode de paiement est masqué à la caisse.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul 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 envoyer le dossier wcp_paymob_pay dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Paymob > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

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

5. Choisissez le Paymob country et saisissez la clé d'API, l'ID d'intégration, l'ID d'iFrame et le secret HMAC (voir Configuration).

6. Dans le tableau de bord Paymob, définissez les URL de callback de votre intégration sur l'URL affichée sur la page des réglages (voir Callbacks).

7. Activez Enable/Disable. Testez un paiement avec l'ID d'une intégration de test Paymob, puis saisissez l'ID de votre intégration en production.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Paymob. Au-dessus des champs, la page vous avertit lorsqu'une des quatre valeurs Paymob manque (tant qu'elle n'est pas renseignée, Paymob n'apparaît pas à la caisse) et lorsque la devise de la boutique n'est pas acceptée par le pays Paymob sélectionné. Un encadré affiche l'URL de callback avec un bouton Copy et un lien vers le tableau de bord Paymob du pays sélectionné.

Général

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

Title : le nom du mode de paiement que les clients voient à la caisse. Par défaut : Paymob.

Description : le texte affiché sous le mode de paiement à la caisse. Par défaut : Pay securely by card or mobile wallet on the Paymob payment page.

Compte Paymob

Toutes les valeurs se trouvent dans votre tableau de bord marchand Paymob. Il n'existe pas de mode test distinct : pour les paiements de test, saisissez l'ID d'intégration d'une intégration en mode test. Aucun autre réglage ne change.

Paymob country : le pays de votre compte Paymob. Il sélectionne le serveur d'API et de page de paiement, et la devise de la boutique doit être celle de ce pays. Par défaut : Egypt.

API key : dans le tableau de bord Paymob, sous Settings > Account info > API Key.

Integration ID : dans le tableau de bord Paymob, sous Developers > Payment Integrations : l'ID numérique de l'intégration en ligne par carte ou portefeuille. Les modes de paiement proposés sur la page Paymob sont ceux de cette intégration.

iFrame ID : dans le tableau de bord Paymob, sous Developers > iframes : l'ID numérique de l'iFrame de paiement.

HMAC secret : dans le tableau de bord Paymob, sous Settings > Account info > HMAC. Obligatoire : les commandes ne sont marquées payées que par des callbacks signés avec ce secret.

Integration ID et iFrame ID ne doivent contenir que des chiffres. Les espaces sont supprimés. Toute autre valeur est refusée à l'enregistrement avec le message que le champ must contain digits only — the previous value was kept.

Callbacks

Paymob signale chaque transaction à votre boutique. Dans le tableau de bord Paymob, ouvrez Developers > Payment Integrations, choisissez votre intégration, cliquez sur Edit et définissez à la fois Transaction processed callback et Transaction response callback sur l'URL affichée sur la page des réglages. Elle ressemble à https://your-site/wc-api/paymob_pay/. Copiez-la avec le bouton Copy. Définissez les URL dans chaque intégration que vous utilisez, y compris l'intégration de test.

Le callback de transaction traitée est envoyé par le serveur Paymob. Le callback de réponse de transaction ramène le client sur votre boutique. Les deux sont signés avec votre secret HMAC et vérifiés par l'extension. Les callbacks sans signature valide sont refusés et ne modifient rien. Si le callback serveur arrive en retard ou se perd, un retour signé du client confirme aussi le paiement.

Avancé

Debug log : Log payment steps and callbacks écrit les étapes de paiement et les callbacks dans WooCommerce > Status > Logs, source wcp_paymob_pay. Les erreurs et les callbacks refusés sont toujours journalisés. Les clés, les jetons et les données clients ne sont jamais écrits. Par défaut : désactivé.

Clean uninstall : Delete the plugin settings and logs when the plugin is deleted. La désactivation de l'extension ne supprime jamais rien. Les identifiants Paymob enregistrés sur les commandes sont conservés. Par défaut : désactivé.

Paiement

Le client choisit le mode de paiement (par défaut Paymob) et passe commande. L'extension crée une nouvelle commande Paymob pour le total de la commande dans la devise de la commande, transmet à Paymob le nom, l'e-mail, le téléphone et l'adresse de facturation du client, et envoie le client vers la page de paiement Paymob de votre pays. Là, le client paie avec l'un des modes de votre intégration, par exemple une carte ou un portefeuille mobile.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée payée qu'une fois que Paymob la confirme par une transaction signée. Un paiement réussi, en attente ou autorisé mène le client à la page de confirmation de commande.

Si le paiement a été refusé, le client revient au paiement (ou à la page Pay for order, si le paiement y avait été lancé) avec le message Your Paymob payment was not completed. Please try again or choose another payment method. Chaque nouvelle tentative crée sa propre commande Paymob, de sorte que le client peut réessayer la même commande. Si le retour de Paymob ne peut pas être vérifié, le client voit We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment.

Si Paymob ne peut pas démarrer le paiement, le client voit un court message et peut choisir un autre mode de paiement, par exemple Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. ou Could not connect to Paymob. Please try again in a moment. La raison technique est écrite dans le journal.

Le mode de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Sur la page Pay for order, c'est la devise de la commande qui est contrôlée et non celle de la boutique. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension prend en charge les paiements uniques sur la page Paymob. Elle ne gère ni cartes enregistrées, ni abonnements, ni formulaire de carte intégré à votre site, ni remboursements depuis WooCommerce.

Commandes

Statuts de commande

Pending payment : le client a été envoyé vers Paymob et n'a pas encore payé, ou Paymob n'a pas encore confirmé le paiement.

Processing : Paymob a confirmé le paiement. Les commandes ne contenant que des produits virtuels téléchargeables passent en Terminée, valeur par défaut de WooCommerce. La note de commande indique la transaction Paymob, le montant et le type de carte avec les quatre derniers chiffres. L'ID de transaction est l'ID de transaction Paymob.

On hold : le paiement est en attente chez Paymob, par exemple un paiement en espèces ou en borne ; ou Paymob n'a qu'autorisé le montant sans le capturer (capturez-le dans le tableau de bord Paymob, la commande est terminée à l'arrivée du callback de capture) ; ou le montant ou la devise payés diffèrent de la commande ; ou un paiement est arrivé pour une commande annulée. La note de commande explique la raison.

Failed : Paymob a refusé le paiement d'une commande en attente. Le client peut payer à nouveau.

Si un second paiement réussi arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de rembourser le doublon dans le tableau de bord Paymob. Un paiement pour une commande annulée qui avait été payée auparavant, ou pour une commande remboursée, ajoute seulement une note : la commande n'est pas rouverte.

Remboursements

Les remboursements depuis WooCommerce ne sont pas pris en charge. Remboursez ou annulez le paiement dans le tableau de bord Paymob. Lorsque Paymob signale un remboursement ou une annulation, une note est ajoutée à la commande, et son statut ne change pas. Mettez la commande à jour manuellement, par exemple avec un remboursement manuel dans WooCommerce.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Paymob. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau l'état, 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 seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Paymob n'est pas affiché aux clients à la caisse. Si un paiement est lancé malgré tout, le client voit This payment method is not available. Please choose another one. Les gestionnaires connectés voient toujours le mode de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Paymob n'apparaît pas à la caisse : vérifiez que la licence est active, que Enable/Disable est activé, que les quatre valeurs (API key, Integration ID, iFrame ID, HMAC secret) sont renseignées et que la devise de la boutique est celle du Paymob country sélectionné. La page des réglages affiche un avertissement lorsqu'un élément manque. Les développeurs disposant d'un compte Paymob multidevise peuvent étendre les devises acceptées avec le filtre paymob_p_supported_currencies.

Le paiement a abouti, mais la commande reste en Pending payment : les callbacks n'atteignent pas votre boutique. Vérifiez que Transaction processed callback et Transaction response callback de l'intégration utilisée correspondent exactement à l'URL affichée sur la page des réglages, et que le HMAC secret est celui du même compte Paymob. Les callbacks refusés sont journalisés comme avertissements sous WooCommerce > Status > Logs, source wcp_paymob_pay, même lorsque le journal de débogage est désactivé.

Le callback répond Invalid signature : le secret HMAC des réglages ne correspond pas au compte Paymob, ou le compte d'un autre pays est sélectionné. Copiez à nouveau le secret HMAC.

Le callback répond Not configured : le secret HMAC est vide. Saisissez le secret ; Paymob renouvellera le callback.

Le callback répond locked : la commande était en cours de mise à jour par une autre requête au même moment, par exemple le retour du client. Paymob renouvellera le callback.

Le client voit une erreur lors de la commande : activez le Debug log et consultez le journal. Paymob payments are temporarily unavailable signifie une clé d'API erronée ou une valeur manquante. Paymob could not start the payment signifie que Paymob a refusé la requête, par exemple à cause d'un ID d'intégration erroné ou de données de facturation incomplètes. This order cannot be paid with Paymob signifie que le total de la commande est égal à zéro.

La commande est En attente après le paiement : lisez la note de commande. Le paiement est en attente (espèces ou borne), la transaction n'a été qu'autorisée (capturez-la dans le tableau de bord Paymob), le montant ou la devise ne correspondaient pas, ou le paiement est arrivé après l'annulation de la commande. La note de commande explique la raison.

Paiements de test : saisissez l'ID d'une intégration de test Paymob dans Integration ID et définissez les URL de callback dans cette intégration. Pour les paiements réels, saisissez à nouveau l'ID de votre intégration en production.

Le bloc de licence affiche une erreur : suivez le message affiché dans le 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 injoignable, l'extension continue de fonctionner avec le dernier état connu.

Désinstallation

La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et l'état de licence de cette extension sont toujours supprimés. Les réglages de la passerelle et les journaux ne sont supprimés que si Clean uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, leurs ID de transaction et leurs ID Paymob.

Paymob est une marque déposée de son propriétaire respectif. Cette extension n'est ni affiliée à Paymob ni approuvée par Paymob.