VibeFox Razorpay 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 Razorpay : il vous faut la Key ID et la Key Secret de votre compte Razorpay pour le mode test, et pour le mode live une fois votre compte activé. Un webhook avec un secret de votre choix est fortement recommandé (voir Configuration). Les paiements dans des devises autres que l'INR nécessitent d'activer International Payments sur votre compte Razorpay.

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 Razorpay Payment 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. Saisissez votre Test Key ID et votre Test Key Secret, configurez le webhook dans le Razorpay Dashboard et saisissez son secret (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Effectuez un paiement test avec Test mode activé. Lorsque vous êtes prêt, saisissez les clés Live et désactivez Test mode.

À l'installation, le module crée deux statuts de commande, Razorpay payment authorized et Razorpay 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 limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Razorpay Payment > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche des avertissements : les clés du mode actuel sont manquantes (Razorpay n'est alors pas affiché au moment du paiement), le Key ID ne commence pas par rzp_test_ en mode test ou par rzp_live_ en mode live, le mode test est activé, le secret du webhook est vide, ou la devise par défaut de la boutique n'est pas l'INR et nécessite International Payments sur votre compte Razorpay. Les espaces collés avec les Key ID sont supprimés à l'enregistrement.

Razorpay

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

Title : le nom du moyen de paiement que voient les clients au moment de payer. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : UPI, Cards, NetBanking. Obligatoire : un titre vide provoque l'erreur Enter a title for the payment method.

Description : le texte affiché sous le moyen de paiement lors du paiement. Par défaut : Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

Clés API

Récupérez vos clés dans le Razorpay Dashboard, sous Account & Settings > API Keys. Passez le Dashboard en mode test pour générer les clés de test (rzp_test_...). Les clés live (rzp_live_...) sont disponibles une fois votre compte activé.

Test mode : utilise les clés du mode test, aucun argent réel n'est donc débité. Par défaut : activé. Désactivez-le pour accepter de vrais paiements. Les paiements, captures et remboursements d'une commande utilisent toujours les clés du mode dans lequel la commande a été payée ; changer de mode plus tard n'affecte donc pas les commandes existantes.

Test Key ID : la Key ID du Razorpay Dashboard en mode test. Elle commence par rzp_test_.

Test Key Secret : la Key Secret du Razorpay Dashboard en mode test.

Live Key ID : la Key ID du Razorpay Dashboard en mode live. Elle commence par rzp_live_.

Live Key Secret : la Key Secret du Razorpay Dashboard en mode live.

Les secrets enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Effacer les secrets enregistrés : cochez Test Key Secret, Live Key Secret ou Webhook Secret et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Paiement

Payment Action : le moment où l'argent est prélevé. Par défaut : Authorize & Capture.

Webhook

Le webhook confirme les paiements même lorsque le client ferme son navigateur juste après avoir payé, et enregistre les remboursements effectués dans le Razorpay Dashboard. Dans le Razorpay Dashboard, allez dans Account & Settings > Webhooks et ajoutez un webhook en mode test et un autre en mode live. Utilisez l'URL affichée dans Webhook URL dans cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_razorpay_payment/webhook, éventuellement avec un code de langue comme /en/. Copiez-la exactement telle qu'elle apparaît dans les réglages. Saisissez dans Razorpay un secret de votre choix et sélectionnez ces événements (ils sont aussi listés dans cette section) :

Webhook Secret : le secret saisi lors de la création du webhook. Utilisez le même secret pour le webhook test et le webhook live, car le module n'a qu'un seul champ pour les deux. Les webhooks sans signature valide sont rejetés. Sans webhook, un paiement n'est confirmé que lorsque le client revient de la fenêtre, ou lorsque le client relance le paiement pour le même panier plus tard.

Avancé

Enable Logging : le journal est écrit dans logs/razorpay_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours journalisés ; cette option ajoute les détails de débogage. Les clés, les signatures et les données de contact du client ne sont jamais journalisées. Par défaut : désactivé.

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

Delete Data on Uninstall : lorsque l'option est activée, la désinstallation du module supprime ses réglages et le journal. Les commandes, les transactions et remboursements Razorpay et les statuts de commande du module sont toujours conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut UPI, Cards, NetBanking) et confirme. Le module crée une commande Razorpay pour le total exact du panier et la devise, puis ouvre la page Razorpay payment de votre boutique. La fenêtre Razorpay Checkout s'ouvre automatiquement sur cette page, avec le nom, l'e-mail et le téléphone du client déjà renseignés. Le paiement apparaît dans Razorpay sous le libellé Cart et le numéro du panier. Aucune commande PrestaShop n'existe encore à ce stade. Si la fenêtre est fermée, le client peut cliquer sur Pay Now pour la rouvrir ou sur Choose another payment method pour revenir au paiement. Le panier est conservé. En mode test, la page affiche Razorpay Test mode: no real money will be charged.

Après un paiement réussi, le client voit Please wait while we process your payment... Le module vérifie la signature Razorpay, récupère le paiement via l'API Razorpay et compare le montant et la devise avec le panier. La commande n'est marquée comme payée qu'après la confirmation de Razorpay. Elle est alors créée, et le client voit la page standard de confirmation de commande. Si la signature est valide mais que le paiement ne peut pas être récupéré à ce moment-là, la commande est créée au statut Razorpay payment on hold et le webhook la confirme plus tard.

Si le client relance le paiement pour le même panier, le module réutilise sa commande Razorpay lorsque le montant, la devise et le mode n'ont pas changé. Si cette commande Razorpay a déjà été payée, par exemple parce que le client a fermé son navigateur et qu'il n'y a pas de webhook, le module crée la commande à partir de ce paiement au lieu de demander un second règlement. Si le total du panier a changé, une nouvelle commande Razorpay est créée.

Messages que le client peut voir :

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 en charge que les paiements uniques. Il ne gère ni abonnements ni paiements récurrents, ni cartes enregistrées, ni Razorpay Magic Checkout, ni Payment Links ou Route (paiements fractionnés), ni widgets d'offres ou de financement.

Commandes et remboursements

Statuts de commande

No order yet : le client n'a pas payé, ou Razorpay n'a pas encore confirmé le paiement. Seul le panier existe. Une tentative de paiement échouée ne crée pas de commande ; le client peut payer de nouveau.

Payment accepted : le paiement a été capturé et confirmé. Il est enregistré avec l'identifiant de paiement Razorpay (pay_...) comme identifiant de transaction, et une note indique l'identifiant du paiement, le montant et la manière dont il a été confirmé (callback, webhook, sync ou admin).

Razorpay payment authorized : le paiement a seulement été autorisé (Authorize Only). Capturez-le pour finaliser la commande.

Razorpay payment on hold : défini dans les cas suivants, chacun avec une note : le montant ou la devise payés ne correspondent pas au panier (par exemple, le panier a été modifié après le début du paiement), le paiement a été capturé pour une commande annulée, ou le paiement n'a pas pu être vérifié via l'API Razorpay à ce moment-là. Un montant payé dans la devise de la commande est enregistré sur la commande. Vérifiez la commande et traitez-la, ou remboursez le paiement.

Cancelled : un paiement qui arrive plus tard pour une commande annulée ne rouvre pas automatiquement la commande : un paiement autorisé n'est pas capturé et reçoit seulement une note, et un paiement capturé place la commande en Razorpay payment on hold. Une notification répétée du paiement qui a déjà réglé la commande ne change rien, même si vous avez annulé la commande entre-temps.

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

Si un paiement supplémentaire arrive pour une commande déjà payée, la commande ne change pas. Une note vous invite à le rembourser dans le Razorpay Dashboard s'il n'était pas voulu. Un payment.failed tardif pour une commande payée ajoute seulement une note.

Bloc de paiement Razorpay

La page de commande affiche un bloc Razorpay payment avec l'identifiant de paiement Razorpay, la commande Razorpay, le statut du paiement, Paid / refunded (le montant débité par Razorpay et le montant remboursé), un badge Test mode pour les paiements test, l'historique des remboursements et les Razorpay notes de la commande. La capture et les remboursements nécessitent le droit de modifier les commandes ; l'accès à la configuration du module n'est pas nécessaire.

Capture (Authorize Only)

Ouvrez la commande au statut Razorpay payment authorized, cliquez sur Capture Razorpay payment dans le bloc Razorpay et confirmez. Le paiement est capturé dans le mode où il a été autorisé, et la commande passe à Payment accepted. Si Razorpay refuse, le bloc et les notes affichent Razorpay capture failed: suivi du motif. Une capture effectuée dans le Razorpay Dashboard finalise la commande grâce au webhook.

Remboursements

Dans le bloc Razorpay, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Razorpay. Confirmez la question Refund this amount through Razorpay? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Les remboursements sont effectués dans le montant et la devise débités par Razorpay ; ainsi, après un écart de montant, vous pouvez rembourser jusqu'à ce que le client a réellement payé, et non jusqu'au total de la commande. Un montant supérieur affiche Invalid refund amount: at most suivi du montant. Le remboursement est envoyé avec les clés du mode dans lequel le paiement a été effectué. Si Razorpay n'accepte pas le remboursement, le bloc affiche Razorpay refund failed: suivi du motif, et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant du remboursement Razorpay, le montant et le statut. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois le paiement capturé.

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 Razorpay.

Les remboursements effectués dans le Razorpay Dashboard arrivent par webhook et sont enregistrés une seule fois dans l'historique des remboursements et les notes. Lorsque la commande est entièrement remboursée, son statut devient Refunded. Un remboursement du Dashboard dans une autre devise ou supérieur au montant remboursable n'est pas enregistré automatiquement ; une note vous demande de le saisir manuellement.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Razorpay Payment est le premier bloc de la page Modules > Module Manager > VibeFox Razorpay Payment > 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-razorpay et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission 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, Razorpay n'est pas proposé 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, si bien que le moyen de paiement vous est aussi masqué : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du paiement. 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 captures et 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é 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 la licence.

Dépannage

Razorpay n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel dispose des deux clés : Test Key ID et Test Key Secret en mode test, Live Key ID et Live Key Secret en mode live. La page de réglages affiche un avertissement lorsqu'elles sont manquantes. 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. Dans le Razorpay Dashboard, vérifiez que le webhook existe dans le mode que vous utilisez (test ou live), que son URL est exactement celle affichée dans Webhook URL et que les cinq événements sont sélectionnés. Vérifiez que Webhook Secret est le même secret que dans Razorpay. La commande est aussi créée lorsque le client revient de la fenêtre ou relance le paiement pour le même panier.

Le webhook répond Webhook secret not configured : Webhook Secret est vide. Saisissez le secret du webhook Razorpay. Razorpay renverra l'événement plus tard.

Le webhook répond Invalid signature ou Missing signature : le secret des réglages est différent du secret du webhook Razorpay. Saisissez le même secret aux deux endroits, pour le webhook test et le webhook live.

Le webhook répond Retry later : le module n'a pas pu confirmer une capture auprès de l'API Razorpay, la commande n'a pas pu être créée (par exemple, parce que le module est désactivé), ou le panier était en cours de mise à jour par une autre requête au même moment. Razorpay renvoie l'événement automatiquement. Le motif figure dans le Log.

L'URL du webhook affiche Method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de Razorpay.

Une commande est Razorpay payment on hold : lisez les notes dans le bloc Razorpay. Le montant ou la devise ne correspondait pas au panier, le paiement est arrivé pour une commande annulée, ou il n'a pas pu être vérifié via l'API Razorpay à ce moment-là et attend le webhook.

Le client voit une erreur lors du paiement : consultez le champ Log sur la page du module. Les erreurs sont journalisées même avec Enable Logging désactivé. Des clés incorrectes affichent le message indiquant que le moyen de paiement n'est pas disponible pour le moment. Les autres motifs de Razorpay sont affichés après Razorpay could not accept this payment:.

La fenêtre ne s'ouvre pas : le script Razorpay Checkout a été bloqué par un bloqueur de contenu ou par la connexion. Le client voit un message et peut recharger la page.

La capture ou le remboursement échoue avec un message concernant le mode : le paiement a été effectué en mode test ou en mode live, et les clés de ce mode ne sont pas renseignées. Saisissez-les et réessayez.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Razorpay Payment 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 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 transactions et remboursements Razorpay et les statuts de commande Razorpay payment authorized et Razorpay payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être capturées et remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Razorpay est une marque de son propriétaire respectif. Ce module n'est pas affilié à Razorpay et n'est pas approuvé par Razorpay.