VibeFox Cashfree for WooCommerce — Aide

Prérequis

WordPress: 5.8 ou ultérieur.

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

PHP: 8.0 ou ultérieur.

HTTPS: Cashfree n'envoie les webhooks qu'aux 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 de passer en production.

Compte Cashfree : vous avez besoin de l'App ID et de la clé secrète (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 clé secrète sert aussi à vérifier les webhooks : il n'existe donc pas de secret de webhook séparé. La devise de la commande 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi téléverser le dossier wcp_cashfree_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

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

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

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

6. Une fois prêt, saisissez l'App ID et la Secret Key de production, puis décochez Sandbox Mode.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Cashfree Payments. Lorsque le moyen de paiement est activé, la page vous avertit si les clés API du mode sélectionné manquent (le moyen de paiement est alors masqué au paiement) 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 moyen de paiement activé sans les clés du mode sélectionné, un message d'erreur indique qu'il reste masqué au paiement tant que ces clés ne sont pas saisies.

Général

Enable/Disable: Enable Cashfree Payments 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 paiement. Par défaut : Cashfree Payments.

Description: le texte affiché sous le moyen de paiement au paiement. Par défaut : Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode et clés API

Récupérez votre App ID et votre clé secrète dans le Cashfree Merchant Dashboard, sous Developers > API Keys. Les clés de test et de production sont différentes ; saisissez chacune dans sa propre section.

Sandbox Mode: Enable Sandbox (test) 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. Par défaut : activé. Décochez-le pour les paiements réels.

Identifiants sandbox

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

Sandbox Secret Key: la clé secrète de votre environnement de test Cashfree.

Identifiants de production

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

Secret Key: la clé secrète de votre environnement de production Cashfree.

Les commandes conservent l'environnement dans lequel elles ont été créées. Leurs webhooks sont vérifiés et leurs remboursements sont envoyés avec les clés de cet environnement ; gardez donc les clés sandbox renseignées tant que les commandes sandbox n'ont pas été réglées 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 cette section, avec les événements Payment et Refund. Elle ressemble à https://your-site/wc-api/cashfree_p/?action=webhook. Sur un site en HTTPS, l'extension transmet aussi cette URL à Cashfree avec chaque commande. Si votre site n'utilise pas HTTPS, cette section affiche un avertissement.

L'extension traite ces événements :

Cashfree signe chaque webhook avec votre clé secrète. Les webhooks sans signature valide sont rejetés. Les webhooks signés concernant des commandes qui n'ont pas été créées 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 confirmé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 peut confirmer la commande.

Avancé

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

Order ID prefix: les identifiants de commande Cashfree sont formés du préfixe suivi du numéro de commande WooCommerce ; une nouvelle tentative reçoit un numéro à la fin. Laissez vide pour utiliser le préfixe automatique de ce site, 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 message.

Debug log: Log Cashfree API events for debugging. Les erreurs sont toujours journalisées. Lorsqu'il est activé, les appels API et les webhooks sont aussi écrits dans WooCommerce > Status > Logs, source wcp_cashfree_payment. Les clés et les données clients ne sont jamais journalisées. Par défaut : désactivé.

Delete Data on Uninstall: Delete all plugin data when uninstalling. Lorsqu'elle est activée, la suppression de l'extension supprime les réglages Cashfree, les journaux de l'extension et les références Cashfree enregistrées sur les commandes. Les commandes elles-mêmes sont conservées. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Cashfree Payments) et passe sa commande. L'extension crée une commande Cashfree pour le total de la commande dans la devise de la commande et ouvre la page Pay for order, qui affiche Redirecting to Cashfree for payment... et charge la page de paiement Cashfree. Si elle ne s'ouvre pas d'elle-même, le client peut cliquer sur Pay Now. Sur la page Cashfree, le client paie avec n'importe quel moyen activé sur votre compte Cashfree, par exemple carte, UPI, banque en ligne ou portefeuille électronique.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après confirmation de Cashfree : par le webhook signé ou par une requête côté serveur adressée à Cashfree lorsque le client revient. Si la banque n'a pas encore confirmé le paiement, la page de confirmation de commande 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.

Si le paiement échoue ou si le client quitte la page Cashfree sans payer, il revient sur la page Pay for order avec The Cashfree payment was not completed. Please try again or choose another payment method. Un paiement Cashfree ouvert est réutilisé lorsque le client réessaie. Si le total de la commande 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, de sorte que la commande ne peut pas être payée deux fois. Si la commande était déjà payée chez Cashfree sans avoir été enregistrée, la tentative suivante enregistre le paiement au lieu de débiter à nouveau.

Si Cashfree ne peut pas démarrer le paiement, le client voit We could not start the Cashfree payment. Please try again or choose another payment method. La raison technique est écrite dans le journal. Une commande d'un montant inférieur au minimum Cashfree (1 unité de la devise ; 0,01 pour BHD, JOD, KWD et OMR, 0,1 pour TND) ne peut pas être payée avec Cashfree.

Le moyen de paiement fonctionne avec le paiement classique, avec le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS). Les textes destinés aux clients sont traduits en hindi.

L'extension ne prend que des paiements uniques sur la page de paiement Cashfree. Elle 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 : la commande est débitée dans la devise de la commande.

Commandes et remboursements

Statuts de commande

Pending payment: le client a été envoyé vers Cashfree et n'a pas encore payé, ou le paiement est encore en attente auprès de la banque. Lorsque le client revient avec un paiement en attente, une note indique que l'extension attend le webhook Cashfree.

Processing: le paiement a été confirmé (les commandes ne contenant que des produits virtuels téléchargeables passent à « Terminée », comportement par défaut de WooCommerce). La note de commande indique l'identifiant de transaction Cashfree et le groupe de moyen de paiement. L'identifiant de transaction de la commande est l'identifiant de paiement Cashfree. Un paiement reçu après l'annulation de la commande est tout de même enregistré, car le montant a bien été prélevé.

On hold: Cashfree a signalé un montant ou une devise payé différent du total de la commande. La note de commande indique le montant attendu, le montant reçu et l'identifiant de transaction. Vérifiez le paiement dans le tableau de bord Cashfree, puis terminez ou remboursez la commande manuellement.

Failed: le paiement a échoué ou a été annulé chez Cashfree. La note indique le statut et la raison donnés par Cashfree. Chaque nouvelle tentative échouée ajoute une note.

Une commande payée n'est jamais remise en arrière par un webhook ou un retour ultérieur.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Cashfree Payments (le bouton affiche le titre du moyen de paiement). Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé à la commande Cashfree 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é, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement lancé est ajouté aux notes de commande avec son identifiant, son montant et son statut. Le statut final arrive par le webhook de remboursement, sous forme d'une autre note de commande.

Les webhooks de statut de remboursement sont seulement ajoutés sous forme de notes. Ils ne sont pas enregistrés automatiquement comme remboursements 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 > Cashfree Payments. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active et votre domaine. Utilisez Check now pour vérifier à nouveau 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 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, Cashfree n'est pas affiché aux clients au 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 connectés de la boutique voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Extensions et sur les pages WooCommerce. 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, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Cashfree n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode en cours dispose de ses clés : Sandbox App ID et Sandbox Secret Key en mode sandbox, App ID et Secret Key en mode production. Le moyen de paiement est aussi masqué lorsque le total de la commande est inférieur au minimum Cashfree. La page des réglages affiche un avertissement lorsque des clés manquent.

Le paiement a été effectué, mais la commande reste « En attente de paiement » : le webhook ne fonctionne pas. Vérifiez que votre site utilise HTTPS, que l'URL dans Developers > Webhooks est exactement celle affichée dans les réglages et que les événements Payment sont sélectionnés. Vérifiez que la clé secrète des réglages appartient à l'environnement dans lequel la commande a été payée. La commande est aussi confirmée lorsque le client revient dans la boutique après avoir payé, et lors de la tentative de paiement suivante.

Le webhook répond Missing signature ou Invalid signature : l'appel ne contenait pas de signature Cashfree valide, ou la clé secrète des réglages ne correspond pas à l'environnement dans lequel la commande a été créée. Cashfree renvoie le webhook.

Le webhook répond Ignored : le webhook est correctement signé mais concerne une commande qui n'a pas été créée 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 traitement par une autre requête au même moment. Cashfree renvoie le webhook.

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 : activez Debug log et consultez WooCommerce > Status > Logs, source wcp_cashfree_payment. 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 The minimum amount for a Cashfree payment is … : le total de la commande est inférieur au minimum Cashfree pour la devise.

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

Order is On hold after payment: lisez la note de commande. Le montant ou la devise payé était différent de la commande. Terminez la commande ou remboursez le paiement.

Refund fails with a message about sandbox or live mode: la commande a été payée dans cet environnement, et ses clés API ne sont pas renseignées. Saisissez-les puis réessayez.

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 statut 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 le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les données Cashfree enregistrées sur les commandes et les journaux ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

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