VibeFox Razorpay for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

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

PHP : 8.0 ou ultérieur.

Compte Razorpay : vous avez besoin de la Key ID et de 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 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_razorpay_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Razorpay > 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. Saisissez votre Test Key ID et votre Test Key Secret, configurez le webhook dans le Razorpay Dashboard et saisissez son secret (voir Configuration).

6. Activez Enable/Disable et effectuez un paiement test avec Test mode activé. Quand vous êtes prêt, saisissez les clés Live et décochez Test mode.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Razorpay. Au-dessus des champs, la page affiche des avis : les clés du mode actuel sont manquantes (le moyen de paiement est alors masqué au 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 de la boutique n'est pas l'INR et nécessite International Payments sur votre compte Razorpay. Dans la liste des moyens de paiement, Razorpay est signalé comme nécessitant une configuration tant que le mode actuel n'a pas ses clés, et un badge Test mode s'affiche tant que le mode test est activé. Les espaces collés avec les clés sont supprimés à l'enregistrement.

Général

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. Par défaut : UPI, Cards, NetBanking.

Description : le texte affiché sous le moyen de paiement au moment de payer. 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 des clés de test (rzp_test_...). Les clés live (rzp_live_...) sont disponibles une fois votre compte activé.

Test mode : Use the Test mode keys (no real money is charged). Par défaut : activé. Décochez-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.

Paiement

Payment Action : le moment où l'argent est débité. 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 cette section des réglages. Elle ressemble à https://your-site/wc-api/razorpay_p_webhook/. 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 :

Webhook Secret : le secret que vous avez saisi lors de la création du webhook. Utilisez le même secret pour le webhook test et le webhook live, car l'extension ne dispose que d'un 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 rouvre plus tard la page de paiement de la commande.

Avancé

Enable Logging : Save debug logs. Le journal se trouve dans WooCommerce > Status > Logs, source wcp_razorpay_payment. Les erreurs et avertissements sont toujours journalisés ; cette option ajoute les détails de débogage. Les clés, les signatures et les coordonnées des clients ne sont jamais journalisées. Par défaut : désactivé.

Delete Data on Uninstall : Remove the plugin settings and logs when the plugin is deleted (orders are never touched). Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut UPI, Cards, NetBanking) et passe sa commande. L'extension crée une commande Razorpay pour le montant total exact et la devise, et ouvre la page de paiement de la commande. 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. Si la fenêtre est fermée, le client peut cliquer sur Pay Now pour la rouvrir ou sur Cancel order. En mode test, la page affiche Razorpay Test mode: no real money will be charged.

Après un paiement réussi, l'extension vérifie la signature Razorpay, récupère le paiement via l'API Razorpay et compare le montant et la devise à ceux de la commande. La commande n'est marquée payée qu'après confirmation de Razorpay. Le client voit alors la page 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 passe au statut « En attente » et le webhook la confirme plus tard.

Si le client revient sur une commande non payée, l'extension réutilise sa commande Razorpay. Si cette commande Razorpay était déjà payée, par exemple parce que le client a fermé son navigateur et qu'il n'y a pas de webhook, l'extension applique le paiement au lieu de demander un second règlement.

Messages visibles par le client :

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension ne prend que les paiements uniques. Elle ne gère ni abonnements ni paiements récurrents, ni cartes enregistrées, ni Razorpay Magic Checkout, ni Payment Links, ni Route (paiements fractionnés), ni widgets d'offres ou de financement.

Commandes et remboursements

Order statuses

Pending payment : la commande Razorpay a été créée et le client n'a pas encore payé. Chaque commande Razorpay est ajoutée aux notes de commande avec son montant et son mode.

Processing or Completed : le paiement a été capturé et confirmé, c'est le statut par défaut de WooCommerce après paiement. La note de commande indique l'ID de paiement Razorpay, le montant et la manière dont il a été confirmé (rappel, webhook ou vérification au retour). L'ID de transaction est l'ID de paiement Razorpay (pay_...).

On hold : défini dans les cas suivants, chacun accompagné d'une note de commande : le paiement n'a été qu'autorisé (Authorize Only), le montant ou la devise payé ne correspond pas à la commande, 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à. Une commande déjà « En attente » reçoit tout de même la note.

Failed : le webhook payment.failed est arrivé pour une commande en attente. La note affiche l'erreur Razorpay. Le client peut toujours payer à nouveau ; une commande qui a déjà un paiement autorisé ou capturé n'est pas modifiée.

Cancelled : le client a cliqué sur Cancel order, ou la commande a été annulée par vous ou par le délai d'expiration de la réserve de stock WooCommerce. Un paiement qui arrive plus tard ne la rouvre pas automatiquement : un paiement autorisé n'est pas capturé, et un paiement capturé place la commande au statut « En attente » pour votre vérification.

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.

Capture (Authorize Only)

Ouvrez la commande au statut « En attente », choisissez Capture Razorpay payment dans Order actions et cliquez sur le bouton de mise à jour. Le paiement est capturé dans le mode où il a été autorisé, et la commande passe à payée. Si Razorpay refuse, la note de commande affiche Razorpay capture failed: avec le motif. Une capture effectuée dans le Razorpay Dashboard finalise la commande via le webhook.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via, suivi du titre du moyen de paiement. Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé avec les clés du mode dans lequel le paiement a été effectué. Si Razorpay n'accepte pas le remboursement, WooCommerce affiche Razorpay refund failed: avec le motif, et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec l'ID de remboursement Razorpay, le montant et le statut.

Les remboursements effectués dans le Razorpay Dashboard arrivent par webhook et sont enregistrés sur la commande en tant que remboursements WooCommerce, une seule fois et sans remise en stock des articles. Un remboursement effectué dans le Dashboard dans une autre devise ou supérieur au montant remboursable n'est pas enregistré automatiquement ; une note vous demande de l'enregistrer manuellement.

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 > Razorpay. 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 l'emplacement du domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Razorpay n'est pas affiché aux clients au moment de payer. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de la boutique connectés voient toujours le moyen 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 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

Razorpay n'apparaît pas au moment de payer : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel a ses 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 avis lorsqu'elles manquent.

Le paiement a abouti, mais la commande reste Pending payment : 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 les réglages 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 confirmée lorsque le client rouvre la page de paiement de la commande.

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

Le webhook répond Invalid signature ou Missing signature : le secret des réglages ne correspond pas à celui du webhook Razorpay. Saisissez le même secret aux deux endroits.

Le webhook répond Retry later : l'extension n'a pas pu confirmer une capture auprès de l'API Razorpay, ou la commande était en cours de mise à jour par une autre requête au même moment. Razorpay renvoie automatiquement l'événement.

Une commande est On hold : lisez la note de commande. Le paiement n'a été qu'autorisé (utilisez Capture Razorpay payment), le montant ou la devise ne correspondait pas à la commande, 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 au paiement : ouvrez les notes de commande, ou consultez WooCommerce > Status > Logs, source wcp_razorpay_payment. Les erreurs sont journalisées même si Enable Logging est désactivé. De mauvaises clés 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.

Le remboursement échoue : le remboursement utilise les clés du mode dans lequel le paiement a été effectué. Vérifiez que les clés de ce mode sont renseignées et lisez le motif dans le message d'erreur.

Le bloc de licence affiche une erreur : suivez le message du 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

Désactiver 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 et les journaux (fichiers de log, y compris les fichiers archivés, et entrées de journal dans la base de données) ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes et leurs données Razorpay ne sont jamais supprimées. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

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