VibeFox PayU India 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.

Devise : roupie indienne (INR). PayU India ne facture qu'en roupies. Pour les paniers dans d'autres devises, le moyen de paiement est masqué à la validation de commande.

Numéro de téléphone : PayU exige un numéro de téléphone pour chaque paiement. Rendez le champ téléphone de l'adresse obligatoire, ou au moins visible, dans votre validation de commande.

Compte PayU India : vous avez besoin du Merchant Key et du Merchant Salt (v1) figurant dans PayU Dashboard > Payment Gateway > Key Salt Details. Passez le tableau de bord en Test Mode pour afficher la paire de test. Utilisez Salt v1, et non Salt v2.

Accès Internet à votre boutique : nécessaire pour le webhook optionnel. Sans lui, les commandes sont confirmées lorsque le client revient de PayU.

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 PayU India Payment Gateway dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure et cliquez sur Activate (voir Clé de licence).

4. Saisissez le Test Merchant Key et Salt ainsi que le Live Merchant Key et Salt (voir Configuration).

5. Recommandé : dans PayU Dashboard > Webhooks, ajoutez l'URL du webhook affichée sur la page Configure pour les paiements réussis et échoués.

6. Choisissez le Mode, activez Enable/Disable et cliquez sur Save. Testez un paiement en mode test, puis passez en mode production.

À l'installation, le module crée deux statuts de commande : Awaiting PayU India payment et PayU India 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 ; la devise INR doit rester autorisée pour le module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit si la clé ou le salt du mode actuel est manquant, affiche Test mode is active: payments go to test.payu.in and no real money is charged. en mode test, et affiche une erreur si la devise par défaut de votre boutique n'est pas INR (la passerelle est alors masquée à la validation de commande).

Lors de l'enregistrement, les espaces et sauts de ligne sont supprimés des clés et des salts, car un salt contenant un espace collé ferait échouer chaque réponse de PayU à la vérification.

PayU India

Enable/Disable : Enable PayU India Payment Gateway active ou désactive le moyen de paiement. Par défaut : désactivé. Si vous l'activez sans la clé et le salt du mode actuel, la page vous avertit après l'enregistrement.

Title : le titre du moyen de paiement que le client voit à la validation de commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : PayU India. Obligatoire.

Description : la description du moyen de paiement que le client voit à la validation de commande. Par défaut : Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU.

Identifiants API

Copiez le Merchant Key et le Merchant Salt (v1) depuis PayU Dashboard > Payment Gateway > Key Salt Details. Passez le tableau de bord en Test Mode pour obtenir la paire de test. La section contient un lien Open the PayU Dashboard.

Mode : l'environnement PayU utilisé par les nouveaux paiements.

Les paiements déjà lancés conservent le mode dans lequel ils ont été initiés : leurs résultats sont vérifiés et leurs remboursements envoyés avec la clé et le salt de ce mode, même après le changement de mode.

Live Merchant Key : votre Merchant Key PayU de production.

Live Merchant Salt (v1) : votre Merchant Salt (v1) PayU de production. Il signe les requêtes et vérifie les réponses de PayU. Gardez-le secret.

Test Merchant Key : votre Merchant Key PayU de test, utilisée uniquement en mode test.

Test Merchant Salt (v1) : votre Merchant Salt (v1) PayU de test, utilisé uniquement en mode test.

Les salts enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Clear saved salts : cochez un salt et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

URL de retour et du webhook

Return URL : se présente sous la forme https://your-shop/module/wcp_payu_india_payment/return, éventuellement avec un code de langue comme /en/. Elle est transmise à PayU automatiquement avec chaque paiement ; rien n'est à configurer.

Webhook URL : se présente sous la forme https://your-shop/module/wcp_payu_india_payment/webhook, éventuellement avec un code de langue. Optionnelle mais recommandée : elle confirme les paiements même si le client ferme son navigateur avant de revenir. Ajoutez-la dans PayU Dashboard > Webhooks pour les paiements réussis et échoués. Copiez l'URL exactement telle qu'elle est affichée sur la page Configure. Elle doit être accessible depuis Internet (sans authentification de base ni blocage par pare-feu). Le mode maintenance de la boutique et ses restrictions par pays ne la bloquent pas.

Le webhook transporte le même résultat signé que le retour du client. Les webhooks sans hash PayU valide sont rejetés.

Avancé

Verify Payment : revérifie chaque paiement réussi avec l'API verify_payment de PayU. Recommandé. Si la vérification ne peut pas être menée à bien, la commande est mise en attente au lieu d'être marquée comme payée. Par défaut : activé.

Enable Logging : consigne les événements de la passerelle pour le dépannage dans logs/payu_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 consignés ; cette option ajoute les autres événements, comme chaque formulaire de paiement et chaque résultat PayU. Les clés, les salts et les données personnelles des clients ne sont jamais consignés. 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 : supprime les réglages et les journaux du module lors de sa désinstallation. Les commandes et les enregistrements de transactions PayU ne sont jamais supprimés. Par défaut : désactivé.

Validation de commande

À l'étape de paiement, le client choisit le moyen de paiement (par défaut PayU India) et confirme. Si ni l'adresse de facturation ni l'adresse de livraison ne comporte de numéro de téléphone fixe ou mobile, le client reste à la validation de commande avec PayU India requires a phone number. Please enter your phone number and try again. Sinon, il voit une courte page Thank you for your order. You will be redirected to PayU to complete your payment., qui envoie à la page de paiement hébergée de PayU une requête de paiement signée pour le total du panier. Si le navigateur ne poursuit pas de lui-même, la page propose un bouton Pay with PayU et un bouton Back to checkout. Sur la page de PayU, le client paie par carte, NetBanking, UPI ou portefeuille électronique. Aucune commande n'existe encore à ce stade.

Chaque tentative de paiement reçoit son propre identifiant de transaction PayU, qui commence par le numéro du panier, et est enregistrée avec son montant et son mode. Un paiement effectué sur une ancienne page de paiement ouverte pour le même panier est toujours accepté. Un panier qui a déjà une commande ne reçoit jamais de nouveau formulaire de paiement : le bouton Précédent du navigateur ne peut donc pas lancer un second paiement.

PayU renvoie le résultat avec le client et, si configuré, par webhook. Un résultat n'est accepté qu'avec un hash PayU valide généré avec la clé et le salt du mode dans lequel le paiement a été initié, et seulement pour un identifiant de transaction émis pour ce panier. Lorsque Verify Payment est activé, un résultat réussi est également vérifié via l'API verify_payment de PayU. Le montant payé doit correspondre au montant de la tentative et au total du panier au paisa près, en INR. La commande n'est marquée comme payée qu'après confirmation de PayU de cette manière. Le module gère les résultats PayU suivants :

Après un paiement réussi ou en attente, le client voit la page standard de confirmation de commande. Un paiement en attente ajoute Your PayU payment is pending. The order will be updated as soon as PayU confirms the result — there is no need to pay again., une commande mise en attente ajoute Your payment is being reviewed. We will contact you if anything else is needed., et une commande en Payment error ou Canceled affiche Your PayU payment was not completed. Please contact us about this order.

Après un paiement non abouti, le client revient à la validation de commande avec un message : Payment was not completed. Please try again or choose a different payment method., Payment was cancelled. You may try again. ou, lorsque le résultat n'a pas pu être vérifié, We could not confirm the payment result. If your account was charged, please contact us before paying again. Si le résultat est encore en cours de traitement au retour du client, une page affiche We are confirming your PayU payment. If you completed the payment, your order will be created shortly — please do not pay again. avec un bouton Check again.

Le module ne facture qu'en INR et ne propose pas de traitement multidevise (MCP). Il ne prend pas en charge l'enregistrement des cartes ni la tokenisation, ni les abonnements, ni le formulaire de carte intégré au site (seamless), ni la gestion des EMI ou des offres, ni le paiement en un clic de PayU.

Commandes et remboursements

Statuts de commande

No order yet : le client a été redirigé vers PayU et n'a pas payé, ou le paiement a échoué ou a été annulé. Seul le panier existe.

Payment accepted : le paiement a été confirmé. Il est enregistré avec l'identifiant de transaction PayU (mihpayid) comme ID de transaction, et une note affiche PayU payment successful. Transaction ID: …, Mode: …, Bank: …

Awaiting PayU India payment : un paiement UPI ou NetBanking est encore en attente chez PayU. La commande passe en Payment accepted lorsque PayU le confirme.

PayU India payment on hold : le montant ou la devise payé diffère du panier, l'API verify_payment n'a pas pu être jointe ou n'a pas encore confirmé le paiement, ou un paiement est arrivé pour une commande qui avait été annulée. La note indique la raison. Vérifiez la transaction dans le PayU Dashboard, puis passez la commande en Payment accepted ou annulez-la et remboursez le paiement. Lorsque seule la vérification a échoué, la commande est payée automatiquement lors de la prochaine transmission du résultat.

Payment error : un paiement en attente a été refusé ou annulé plus tard. Un résultat réussi ultérieur paie quand même la commande.

Refunded : tout ce qui a été payé a été remboursé via le module.

Si PayU signale un autre paiement réussi pour une commande déjà payée, la commande n'est pas modifiée et une note vous demande de rembourser le doublon dans le PayU Dashboard. Un paiement PayU pour un panier commandé avec un autre moyen de paiement reçoit une note et ne paie pas cette commande.

Bloc de paiement PayU India

La page de la commande affiche un bloc PayU India payment avec l'identifiant de transaction PayU (mihpayid), l'identifiant de transaction de la boutique (txnid), l'environnement, le statut PayU, le mode et la banque du paiement, le montant payé et le montant des remboursements demandés, un badge Test mode pour les paiements de test, l'historique des remboursements et les notes du module. Pour une commande mise en attente, il affiche un rappel de vérifier le paiement.

Remboursements

Dans le bloc PayU India payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via PayU. Confirmez la question Refund this amount through PayU? This cannot be undone. Les remboursements totaux et partiels sont pris en charge ; le montant doit être supérieur à zéro et ne pas dépasser ce qui reste de ce que PayU a encaissé. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Le remboursement est envoyé via l'API de remboursement de PayU avec la clé et le salt du mode dans lequel le paiement a été effectué ; ces identifiants doivent donc être renseignés. Si PayU refuse le remboursement, le bloc affiche PayU refund failed: avec le message de PayU, et aucun remboursement n'est enregistré.

PayU met les remboursements en file d'attente et les traite de manière asynchrone ; le client reçoit généralement l'argent sous 5–7 jours ouvrés. L'historique des remboursements et les notes affichent le montant, l'identifiant de requête PayU et le motif. Un remboursement total passe la commande en Refunded ; un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles dès que PayU a communiqué l'identifiant de transaction du paiement. Le module ne vérifie pas ensuite le statut du remboursement et ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via PayU.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox PayU India Payment Gateway est le premier bloc de la page Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, l'état (par exemple la date jusqu'à laquelle la licence est active et votre domaine) et les boutons Check now pour vérifier à nouveau l'état, 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-payu-india 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 état 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, PayU India n'est pas affiché aux clients à la validation de 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 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 pas le tester à la validation de 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 arrive à expiration, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement pendant votre travail dans le back office : une fois par jour pendant les 14 premiers jours suivant 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 l'état de la licence.

Dépannage

PayU India n'apparaît pas à la validation de commande : vérifiez que la licence est active, que Enable/Disable est activé et que la clé et le salt du Mode sélectionné sont renseignés. Vérifiez que la devise du panier est INR et que le module est autorisé pour cette devise, le pays du client et son groupe dans Payment > Preferences. La page Configure affiche un avertissement pour les identifiants manquants et pour une devise de boutique différente de INR.

Le paiement a été effectué, mais aucune commande n'a été créée : le client n'est pas revenu dans la boutique et aucun webhook n'est arrivé. Ajoutez l'URL du webhook de la page Configure dans PayU Dashboard > Webhooks pour les paiements réussis et échoués, et assurez-vous qu'elle est accessible depuis Internet.

Le webhook répond invalid_signature : le hash PayU ne correspond pas. Vérifiez que la clé et le salt du mode du paiement sont corrects et que Salt v1 est utilisé, et non Salt v2. Un résultat d'un paiement de production signé avec le salt de test, ou l'inverse, est également rejeté. Rien n'est modifié.

Le webhook répond not_configured : la clé ou le salt du mode dans lequel le paiement a été initié est manquant. Saisissez-les ; PayU renouvelle le webhook.

Le webhook répond verify_unavailable : l'API verify_payment n'a pas encore pu confirmer le paiement. La commande est mise en attente, et la prochaine transmission effectue une nouvelle vérification.

Le webhook répond busy ou retry : le retour du client pour le même panier était en cours de traitement au même moment, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). PayU renouvelle le webhook. La raison est inscrite dans le journal.

Le webhook répond ignored_unknown_txnid : la transaction n'a pas été initiée par cette boutique, par exemple une autre boutique utilisant le même compte PayU. Rien n'est modifié.

Le client voit PayU India requires a phone number : rendez le champ téléphone de l'adresse obligatoire ou visible dans la validation de commande. L'adresse de facturation est utilisée en premier, puis l'adresse de livraison.

La commande est en PayU India payment on hold : lisez les notes du bloc PayU India payment. La raison est un écart de montant ou de devise, une vérification échouée ou en attente, ou un paiement pour une commande annulée.

Le remboursement échoue : PayU transaction ID not found for this order. signifie que la commande n'a pas encore de paiement PayU. This payment was made in Test mode, but the Merchant Key/Salt of that mode are not set. (ou Live mode) signifie que vous devez d'abord saisir les identifiants de ce mode. Invalid refund amount: at most … INR can be refunded. signifie que le montant est supérieur au reste du paiement.

Trop peu de données dans le journal : les erreurs et avertissements sont toujours écrits ; activez Enable Logging pour voir aussi chaque formulaire de paiement et chaque résultat PayU.

Hook pour développeurs : actionPayuPRequestFields modifie les champs de la requête de paiement avant leur signature. La clé, l'identifiant de transaction, le montant et les URL de retour ne peuvent pas être modifiés par ce biais.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PayU India Payment Gateway et choisissez Uninstall. La clé de licence et l'état de la 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. Sinon, tous les réglages sont conservés pour une réinstallation ultérieure. Les enregistrements de transactions PayU, les demandes de remboursement et les statuts de commande Awaiting PayU India payment et PayU India 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 PayU.

PayU est une marque commerciale de son titulaire respectif. Ce module n'est pas affilié à PayU et n'est pas approuvé par PayU.