VibeFox Cashfree 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 de PHP plus anciennes.

HTTPS : Cashfree n'envoie les webhooks qu'à des URL en https://. Sans HTTPS, les paiements sont tout de même confirmés lorsque le client revient dans la boutique, mais activez HTTPS avant la mise en production.

Compte Cashfree : vous avez besoin de l'App ID et de la Secret Key de votre compte Cashfree, séparément pour l'environnement de test (sandbox) et pour la production, ainsi que d'un webhook dans le Cashfree Merchant Dashboard (voir Configuration). La Secret Key sert aussi à vérifier les webhooks : il n'existe donc pas de clé de webhook distincte. La devise du panier doit être activée pour votre compte Cashfree.

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 Cashfree Payments 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, et cliquez sur Activate (voir Clé de licence).

4. Saisissez le Sandbox App ID et la Sandbox Secret Key, ajoutez le webhook dans le Cashfree Merchant Dashboard (voir Configuration), activez Enable/Disable, cliquez sur Save et testez un paiement.

5. Lorsque tout est prêt, saisissez l'App ID et la Secret Key de production, désactivez Sandbox Mode et cliquez sur Save.

À l'installation, le module crée le statut de commande Cashfree payment on hold. PrestaShop propose 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.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Cashfree Payments > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page indique que la commande n'est créée qu'après confirmation du paiement par Cashfree. Lorsque le mode de paiement est activé, la page vous avertit si les clés API du mode sélectionné sont absentes (le mode de paiement est alors masqué à la commande), et affiche Sandbox mode is on: customers see a test checkout and no real money is charged. tant que le mode sandbox est activé. Si vous enregistrez un mode de paiement activé sans les clés du mode sélectionné, un avertissement indique qu'il restera masqué à la commande tant que ces clés ne sont pas renseignées.

Cashfree Payments

Enable/Disable : Enable Cashfree Payments active ou désactive le mode de paiement. Par défaut : off.

Title : le nom du mode de paiement affiché au client à la commande. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Cashfree Payments. Obligatoire.

Description : le texte affiché sous le mode de paiement à la commande. Par défaut : Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode and API keys

Récupérez votre App ID et votre Secret Key dans le Cashfree Merchant Dashboard, sous Developers > API Keys. Les clés de test et les clés de production sont différentes.

Sandbox Mode : utilise le sandbox Cashfree pour les tests. Aucun argent réel n'est débité, et la page de paiement affiche SANDBOX MODE - no real payments will be processed. sous le mode de paiement. Par défaut : on. Désactivez-le pour les paiements réels.

Sandbox App ID : l'App ID de votre environnement de test Cashfree.

Sandbox Secret Key : la Secret Key de votre environnement de test Cashfree.

App ID : l'App ID de votre environnement de production Cashfree.

Secret Key : la Secret Key de votre environnement de production Cashfree.

Les Secret Keys enregistrées ne sont plus jamais affichées. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement si vous voulez la changer.

Clear saved secrets : cochez une Secret Key et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Les paiements conservent l'environnement dans lequel ils ont été créés. Leurs webhooks sont vérifiés, leur statut est contrôlé et leurs remboursements sont envoyés avec les clés de cet environnement. Gardez donc les clés sandbox renseignées jusqu'à ce que les paiements sandbox soient réglés après le passage en production.

Webhook

Le webhook informe votre boutique qu'un paiement a été effectué, a échoué ou a été remboursé. Dans le Cashfree Merchant Dashboard, allez dans Developers > Webhooks et ajoutez l'URL affichée dans Webhook URL dans cette section, avec les événements Payment et Refund. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_cashfree_payment/webhook. Copiez l'URL exactement telle qu'elle est affichée dans les réglages. Sur une boutique en HTTPS, le module transmet aussi cette URL à Cashfree à chaque paiement. Si votre boutique n'utilise pas HTTPS, cette section affiche un avertissement.

Le module gère ces événements (ils sont également listés dans cette section) :

Cashfree signe chaque webhook avec votre Secret Key. Les webhooks sans signature valide sont rejetés. Un webhook doit être signé avec la Secret Key de l'environnement dans lequel le paiement a été effectué : une clé sandbox ne confirme donc jamais un paiement réel. Les webhooks signés concernant des paiements qui n'ont pas été lancés par cette boutique (par exemple une autre boutique sur le même compte Cashfree) sont acquittés et ignorés. Sans webhook, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé. Si le client ferme son navigateur après avoir payé, seul le webhook (ou la tentative de paiement suivante pour le même panier) peut créer la commande.

Advanced

API Version : la version de l'API Cashfree à utiliser.

Order ID prefix : les identifiants de commande Cashfree sont construits ainsi : préfixe + identifiant du panier PrestaShop ; une nouvelle tentative pour le même panier reçoit un numéro à la fin (par exemple 123-2). Laissez le champ vide pour utiliser le préfixe automatique de cette boutique, affiché dans la description du champ. Utilisez un préfixe différent pour chaque boutique connectée au même compte Cashfree. Lettres, chiffres, « _ » et « - » uniquement, jusqu'à 20 caractères. Les autres caractères sont supprimés à l'enregistrement, avec un avertissement.

Debug log : les erreurs sont toujours journalisées. Lorsqu'il est activé, les appels à l'API Cashfree et les webhooks sont aussi écrits dans logs/cashfree_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés et les données clients ne sont jamais journalisées. Par défaut : off.

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

Delete Data on Uninstall : lorsqu'il est activé, la désinstallation du module supprime les réglages Cashfree et le journal du module. Les commandes, leurs transactions et remboursements Cashfree, ainsi que le statut de commande Cashfree payment on hold, restent toujours en place afin que les commandes existantes continuent de fonctionner. Par défaut : off.

Commande

À l'étape de paiement, le client choisit le mode de paiement (par défaut Cashfree Payments) et confirme. Le module crée une commande Cashfree pour le total du panier dans la devise du panier et ouvre une page de paiement qui affiche Redirecting to Cashfree for payment... et charge la page de paiement Cashfree. Si elle ne s'ouvre pas toute seule, le client peut cliquer sur Pay Now. Sur la page de paiement Cashfree, le client paie avec n'importe quel moyen activé sur votre compte Cashfree, par exemple carte, UPI, banque en ligne ou portefeuille électronique. L'adresse e-mail et le téléphone de facturation du client sont transmis à Cashfree. À ce stade, aucune commande n'existe encore.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après confirmation par Cashfree : par le webhook signé ou par une requête serveur vers Cashfree lorsque le client revient. La commande est alors créée et le client voit la page standard de confirmation de commande. Le retour fonctionne aussi dans un autre navigateur, par exemple lorsque le client revient depuis une application UPI. Si la banque n'a pas encore confirmé le paiement, une page Payment confirmation affiche Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. ainsi qu'un bouton Check again ; le webhook crée la commande dès que la banque confirme le paiement.

Si le paiement échoue ou si le client quitte la page Cashfree sans payer, il revient à la commande avec The Cashfree payment was not completed. Please try again or choose another payment method. Le panier est conservé. Un paiement Cashfree ouvert est réutilisé lorsque le client réessaie. Si le total du panier a changé ou si la session est sur le point d'expirer, l'ancienne commande Cashfree est fermée et une nouvelle est créée, afin que le panier ne puisse pas être payé deux fois. Si le panier a déjà été payé chez Cashfree sans être enregistré, la tentative suivante crée la commande au lieu de débiter à nouveau.

Si Cashfree ne peut pas lancer le paiement, le client reste à la commande avec We could not start the Cashfree payment. Please try again or choose another payment method. La raison technique est écrite dans le journal. Un total de panier inférieur au minimum Cashfree (1 unité de la devise ; 0,01 pour BHD, JOD, KWD, OMR et 0,1 pour TND) ne peut pas être payé avec Cashfree, et le mode de paiement n'est pas affiché pour ce panier.

Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Le module ne prend que des paiements uniques sur la page de paiement Cashfree. Il ne gère ni cartes enregistrées, ni abonnements ni paiements récurrents, ni autorisation puis capture séparées, ni widget d'offres Cashfree, ni paiement à la livraison (COD) ou liens de paiement via Cashfree, ni conversion de devise : le panier est débité dans la devise du panier.

Commandes et remboursements

Order statuses

No order yet : le client a été envoyé vers Cashfree et n'a pas payé, le paiement a échoué, ou le paiement est encore en attente auprès de la banque. Seul le panier existe.

Payment accepted : le paiement a été confirmé. Il est enregistré avec l'identifiant de paiement Cashfree comme identifiant de transaction, et une note indique cet identifiant ainsi que le groupe du mode de paiement (par exemple upi ou credit_card).

Cashfree payment on hold : Cashfree a signalé un montant ou une devise payés qui diffèrent du total du panier (par exemple, le panier a été modifié dans un autre onglet après le début du paiement). La note indique le montant attendu, le montant reçu et l'identifiant de transaction. Vérifiez le paiement dans le tableau de bord Cashfree, puis traitez la commande ou remboursez le paiement.

Refunded : le paiement a été entièrement remboursé via le module.

Un paiement qui arrive après l'annulation de la commande est tout de même enregistré, et la commande redevient payée, car l'argent a été prélevé. Une commande payée n'est jamais remise en arrière par un paiement échoué ultérieur.

Cashfree payment block

La page de commande affiche un bloc Cashfree payment avec l'identifiant de transaction, la commande Cashfree, le statut du paiement, le montant payé et remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les Cashfree notes de la commande.

Refunds

Dans le bloc Cashfree payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Cashfree. Confirmez la question Refund this amount through Cashfree? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Les remboursements sont effectués dans le montant et la devise débités par Cashfree : après un écart de montant, vous pouvez donc rembourser jusqu'à hauteur de ce que le client a réellement payé, et non le total de la commande. Le remboursement est envoyé à la commande Cashfree qui a été payée, dans l'environnement (sandbox ou production) où elle a été payée ; les clés de cet environnement doivent donc être renseignées. Si Cashfree n'accepte pas le remboursement, ou le signale comme annulé ou rejeté, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement lancé est ajouté à l'historique des remboursements et aux notes avec son identifiant, son montant et son statut. Un remboursement total passe la commande en Refunded ; un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que Cashfree a confirmé le paiement.

Le statut final du remboursement arrive par le webhook de remboursement et est ajouté aux notes. Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Cashfree.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Cashfree Payments est le premier bloc de Modules > Module Manager > VibeFox Cashfree Payments > 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-cashfree 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 : celui 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, Cashfree n'est pas affiché aux clients à la commande. 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 mode de paiement est donc masqué aussi pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester à la commande. 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 remboursements fonctionnent.

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 que vous travaillez 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

Cashfree n'apparaît pas à la commande : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel dispose de ses clés : Sandbox App ID et Sandbox Secret Key en mode sandbox, App ID et Secret Key en mode production. La page des réglages affiche un avertissement lorsque les clés manquent. Le mode de paiement est aussi masqué lorsque le total du panier est inférieur au minimum Cashfree. 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 : le webhook ne fonctionne pas. Vérifiez que votre boutique utilise HTTPS, que l'URL indiquée dans Developers > Webhooks est exactement celle affichée dans Webhook URL et que les événements Payment sont sélectionnés. Vérifiez que la Secret Key des réglages appartient à l'environnement dans lequel le paiement a été effectué. Le tableau de bord Cashfree affiche la réponse de votre boutique pour chaque webhook. La commande est aussi créée lorsque le client revient dans la boutique après avoir payé, et à la tentative de paiement suivante pour le même panier.

Le webhook répond Missing signature ou Invalid signature : l'appel ne comportait pas de signature Cashfree valide, ou la Secret Key des réglages ne correspond pas à l'environnement dans lequel le paiement a été effectué. Vérifiez que les clés sandbox et production ne sont pas inversées.

Le webhook répond Ignored : le webhook est correctement signé, mais il concerne un paiement qui n'a pas été lancé par cette boutique, par exemple une autre boutique sur le même compte Cashfree. Donnez à chaque boutique son propre Order ID prefix.

Le webhook répond Busy, retry later : la commande était en cours de création par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Cashfree relance le webhook. Activez Debug log pour voir la raison.

Le client voit The Cashfree payment page could not be loaded : le script Cashfree n'a pas pu être chargé dans le navigateur, par exemple à cause d'un bloqueur. Le client peut cliquer à nouveau sur Pay Now ou sur Choose another payment method.

Le client voit We could not start the Cashfree payment : consultez le champ Log sur la page du module. Les causes habituelles sont des clés incorrectes pour le mode sélectionné ou une devise non activée sur votre compte Cashfree.

Le client voit We could not verify the payment : le lien de retour ne correspondait pas au panier. Si un montant a été débité, le webhook crée tout de même la commande. Vérifiez le paiement dans le tableau de bord Cashfree avant que le client ne paie à nouveau.

La commande est en Cashfree payment on hold après le paiement : lisez les notes du bloc Cashfree payment (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

Le remboursement échoue avec un message concernant le mode sandbox ou production : le paiement a été effectué dans cet environnement, et ses clés API ne sont pas renseignées. Saisissez-les et réessayez.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Cashfree Payments et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete Data on Uninstall est activé, les réglages Cashfree 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 transactions et remboursements Cashfree ainsi que le statut de commande Cashfree payment on hold sont toujours conservés, afin que les commandes payées auparavant puissent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

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