VibeFox Paymob 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.

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 : l'API key, l'integration ID d'une intégration de paiement en ligne, l'iFrame ID de la page de paiement et le HMAC secret.

Devise : la devise du panier 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 moyen de paiement est masqué au moment du paiement. Les comptes Paymob multidevises ne sont pas pris en charge.

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 Paymob Pay 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. Choisissez le Paymob country et saisissez l'API key, l'integration ID, l'iFrame ID et le HMAC secret (voir Configuration).

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

6. Activez Enable/Disable et cliquez sur Save. Testez un paiement avec l'ID d'une intégration de test Paymob, puis saisissez l'ID de votre intégration réelle.

À l'installation, le module crée deux statuts de commande : Awaiting Paymob payment et Paymob payment on hold. PrestaShop active par défaut un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences. Un pays activé plus tard dans votre boutique doit aussi y être coché pour ce module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Paymob Pay > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsqu'une des quatre valeurs Paymob manque (jusque-là, Paymob est masqué au paiement) et lorsque la devise par défaut de la boutique n'est pas acceptée par le pays Paymob sélectionné. Un encadré Callbacks affiche l'URL de callback avec un bouton Copy et un lien vers le tableau de bord Paymob du pays sélectionné.

Paymob

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

Title : le nom du moyen de paiement que voit le client au moment du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Paymob.

Description : le texte affiché sous le moyen de paiement au moment du paiement. Par défaut : Pay securely by card or mobile wallet on the Paymob payment page. Laissez le champ vide pour n'afficher aucun texte.

Compte Paymob

Toutes les valeurs se trouvent dans votre tableau de bord marchand Paymob. Il n'existe pas de mode test séparé : pour les paiements de test, saisissez l'integration ID 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 du panier 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'identifiant numérique de l'intégration en ligne carte ou portefeuille. Les moyens 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'identifiant 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 créées comme payées qu'à partir de callbacks signés avec ce secret.

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

L'API key et le HMAC secret enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Clear saved secrets : cochez API key ou HMAC secret et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

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 réglez Transaction processed callback ainsi que Transaction response callback sur l'URL affichée dans l'encadré Callbacks. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_paymob_pay/callback, éventuellement avec un code de langue comme /en/. L'URL est générée dans la langue par défaut de la boutique. Copiez-la avec le bouton Copy. Renseignez les URL dans chaque intégration que vous utilisez, y compris l'intégration de test.

Le transaction processed callback est envoyé par le serveur Paymob. Le transaction response callback ramène le client dans votre boutique. Les deux sont signés avec votre HMAC secret et vérifiés par le module. Les callbacks sans signature valide sont rejetés et ne modifient rien. Si le callback serveur arrive en retard ou se perd, un retour signé du client confirme aussi le paiement. Le callback serveur fonctionne pendant que la boutique est en mode maintenance et n'est pas bloqué par la restriction par pays de votre boutique.

Avancé

Debug log : écrit les étapes de paiement et les callbacks dans logs/paymob_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et les callbacks rejetés 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 écrits. Par défaut : désactivé.

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

Clean uninstall : lorsqu'elle est activée, la désinstallation du module supprime ses réglages et ses journaux. Les identifiants Paymob enregistrés pour les commandes (tentatives de paiement) et les statuts de commande sont toujours conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Paymob) et confirme. Le module enregistre une nouvelle commande Paymob pour le total du panier dans la devise du panier, transmet à Paymob le nom, l'e-mail, le téléphone et l'adresse de facturation du client, puis envoie le client sur la page de paiement Paymob de votre pays. Là, le client paie avec l'un des moyens de votre intégration, par exemple une carte ou un portefeuille mobile. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation de Paymob par une transaction signée. La commande est alors créée et le client voit la page standard de confirmation de commande. Un paiement en attente (par exemple en espèces ou en borne) ou un paiement autorisé crée également la commande, dans un statut d'attente, et mène à la page de confirmation.

Si la commande est confirmée par le callback Paymob au même moment, le client voit une page avec Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. Pour un paiement en attente, le texte est Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. La page comporte un bouton Check again et un bouton Back to checkout.

Si le paiement a été refusé, le client revient à l'étape de paiement avec le même panier et le message Your Paymob payment was not completed. Please try again or choose another payment method. Chaque nouvelle tentative enregistre sa propre commande Paymob, de sorte que le client peut payer à nouveau le panier. 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 reste à l'étape de paiement avec un message bref, 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 module traite des paiements uniques sur la page Paymob. Il n'y a ni cartes enregistrées, ni abonnements, ni formulaire de carte intégré à votre site, ni remboursement depuis le back office.

Commandes

Statuts de commande

No order yet : le client a été envoyé vers Paymob et n'a pas payé, le paiement a été refusé ou Paymob n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : Paymob a confirmé le paiement. Le paiement est enregistré avec l'ID de transaction Paymob comme ID de transaction, et une note indique la transaction, le montant et le type de carte avec les quatre derniers chiffres.

Awaiting Paymob payment : le paiement est en attente chez Paymob, par exemple un paiement en espèces ou en borne. La commande passe en Payment accepted lorsque Paymob confirme le paiement.

Paymob payment on hold : Paymob n'a fait qu'autoriser le montant sans le capturer (capturez-le dans le tableau de bord Paymob ; la commande passe en Payment accepted lorsque le callback de capture arrive) ; ou le montant ou la devise payés diffèrent du panier (par exemple, le panier a été modifié après le début du paiement) ; ou un paiement est arrivé pour une commande annulée. La note indique la raison. Vérifiez la commande, puis traitez-la ou remboursez le paiement dans le tableau de bord Paymob.

Si un second paiement réussi arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous invite à 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. Un paiement refusé pour une commande qui n'est pas encore payée ajoute seulement une note.

Bloc de paiement Paymob

La page de commande affiche un bloc Paymob payment avec chaque tentative Paymob de la commande : la commande Paymob, l'ID de commande marchand et le pays, l'ID de transaction Paymob, le statut, le montant demandé, le montant indiqué par Paymob pour la carte et le message de Paymob. En dessous figurent les Notes du module pour cette commande.

Remboursements

Les remboursements depuis le back office 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 le statut de la commande ne change pas. Mettez la commande à jour manuellement, par exemple son statut ou un avoir.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Paymob Pay est le premier bloc de Modules > Module Manager > VibeFox Paymob Pay > 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-paymob 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, Paymob n'est pas affiché aux clients au moment 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 boutique 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 ne pouvez pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.

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é à nouveau 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

Paymob n'apparaît pas au moment du paiement : 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 du panier est celle du Paymob country sélectionné. La page de réglages affiche un avertissement lorsqu'un élément manque. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : 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 dans l'encadré Callbacks, et que le HMAC secret est celui du même compte Paymob. Les callbacks rejetés sont écrits dans le journal sous forme d'avertissements, même lorsque Debug log est désactivé. Consultez le champ Log sur la page du module.

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

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

Le callback répond locked ou retry : la commande était en cours de mise à jour par une autre requête au même moment, par exemple le retour du client, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Paymob renouvellera le callback. La raison est écrite dans le journal.

Ouvrir l'URL du callback dans le navigateur mène au paiement avec le message could not verify : c'est normal. L'URL n'accepte que les requêtes signées de Paymob.

Le client voit une erreur en choisissant Paymob : activez Debug log et consultez le journal. Paymob payments are temporarily unavailable signifie une API key erronée ou une valeur manquante. Paymob could not start the payment signifie que Paymob a rejeté la demande, par exemple à cause d'un integration ID incorrect ou de données de facturation incomplètes. This order cannot be paid with Paymob signifie que le total de la commande est nul. Paymob does not accept payments in suivi d'une devise signifie que la devise du panier n'est pas celle du pays Paymob sélectionné.

La commande est en Paymob payment on hold ou en Awaiting Paymob payment après le paiement : lisez les notes du bloc Paymob payment. 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 correspondait pas, ou le paiement est arrivé après l'annulation de la commande.

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 réelle.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Paymob Pay et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Clean uninstall est activé, les réglages du module et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les tentatives de paiement Paymob des commandes et les statuts de commande Awaiting Paymob payment et Paymob payment on hold sont toujours conservés. 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. Ce module n'est ni affilié à Paymob ni approuvé par Paymob.