VibeFox PayU for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

Devise : l'une des devises PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH. La devise doit également être activée pour votre point de vente chez PayU. Pour les autres devises, l'option de paiement est masquée dans le tunnel de commande.

Accès Internet à votre boutique : PayU envoie les notifications de paiement à votre boutique ; elle doit donc être accessible depuis Internet (pas derrière une authentification HTTP ni un pare-feu). Sans notifications, les paiements sont tout de même vérifiés lorsque le client revient de PayU.

Compte PayU : vous avez besoin de quatre clés de votre point de vente (POS) : POS ID, Second key (MD5), client_id OAuth et client_secret OAuth. Elles se trouvent dans le panneau marchand PayU, sous Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Les clés sandbox proviennent d'un compte sandbox PayU distinct.

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 Payment 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 les quatre clés Sandbox et les quatre clés Live (voir Configuration). Aucune URL de notification n'est à configurer dans PayU.

5. Activez Enable/Disable et cliquez sur Save. Laissez Test Mode activé jusqu'à ce que vous ayez effectué un paiement test, puis désactivez-le pour accepter de vrais paiements avec les clés Live.

À l'installation, le module crée deux statuts de commande : Awaiting PayU payment confirmation et PayU payment on hold. PrestaShop active 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 PayU Payment > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit pendant que le mode sandbox est activé (Le mode sandbox (test) est activé : les paiements sont envoyés à la sandbox PayU et aucun argent réel n'est débité. N'expédiez pas de commandes payées en mode test.), lorsqu'une des quatre clés du mode actif est manquante et lorsque PayU n'accepte pas la devise par défaut de la boutique. Dans les deux derniers cas, PayU n'est pas affiché dans le tunnel de commande.

Lors de l'enregistrement, les espaces et les sauts de ligne sont supprimés de toutes les clés, car la copie depuis le panneau PayU en ajoute souvent. Un Title vide n'est pas enregistré : la page affiche Saisissez un titre pour le moyen de paiement.

PayU

Enable/Disable : Enable PayU payment gateway active ou désactive l'option de paiement. Par défaut : désactivé.

Title : le titre du moyen de paiement affiché au client. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : PayU. Obligatoire.

Description : la description du moyen de paiement affichée au client dans le tunnel de commande. Par défaut : Pay securely via PayU.

Identifiants API

Retrouvez les clés dans le panneau marchand PayU : Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Les clés sandbox proviennent d'un compte sandbox PayU distinct. Les quatre clés d'un mode doivent être renseignées.

Test Mode : utilise la sandbox PayU et les clés Sandbox ci-dessous. Aucun argent réel n'est débité. Tant qu'il est activé, les clients voient Le mode sandbox est activé : aucun paiement réel n'est effectué. sous l'option de paiement. Désactivez-le pour accepter de vrais paiements avec les clés Live. Par défaut : activé.

Live POS ID : le POS ID (merchantPosId) de votre point de vente de production.

Live Second Key (MD5) : sert à vérifier la signature des notifications PayU.

Live OAuth Client ID : le client_id OAuth du point de vente.

Live OAuth Client Secret : le client_secret OAuth du point de vente.

Sandbox POS ID : le POS ID de votre point de vente sandbox PayU.

Sandbox Second Key (MD5) : sert à vérifier la signature des notifications de la sandbox PayU.

Sandbox OAuth Client ID : le client_id OAuth du point de vente sandbox.

Sandbox OAuth Client Secret : le client_secret OAuth du point de vente sandbox.

Les Second Keys et client secrets enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Enregistré — laissez vide pour le conserver. Ne saisissez une nouvelle valeur que pour la modifier. Les POS ID et client ID sont affichés tels qu'enregistrés.

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

Chaque paiement mémorise son environnement. Les notifications, les vérifications d'état et les remboursements d'un paiement utilisent toujours les clés de cet environnement ; les anciens paiements continuent donc de fonctionner après un changement de mode. Une notification signée avec la clé sandbox n'est jamais acceptée pour un paiement live, et inversement.

Notifications de paiement

Notification URL : affiche l'adresse à laquelle PayU envoie les notifications. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_payu_payment/webhook, éventuellement avec un code de langue. Le module l'envoie à PayU avec chaque paiement ; rien n'est donc à configurer dans le panneau PayU. Vérifiez qu'elle est accessible depuis Internet (non bloquée par un pare-feu ou une authentification HTTP). Les notifications fonctionnent également lorsque la boutique est en maintenance et ne sont pas bloquées par la restriction par pays de votre boutique.

Avancé

Receive payments automatically : réceptionne automatiquement les paiements en attente de confirmation. Cela n'a d'importance que si la réception automatique est désactivée pour votre point de vente dans le panneau PayU : les paiements attendent alors une confirmation (WAITING_FOR_CONFIRMATION). Lorsque cette option est activée, le module réceptionne immédiatement ces paiements et la commande est créée dès que PayU indique le paiement comme terminé. Lorsqu'elle est désactivée, ou si la réception échoue, la commande est créée en Awaiting PayU payment confirmation et vous réceptionnez ou annulez le paiement avec les boutons du bloc PayU de la commande. Par défaut : activé.

Logging : écrit les événements techniques (numéros de panier et de commande, identifiants de commandes PayU, statuts, erreurs ; aucune clé ni donnée personnelle) dans logs/wc_pu_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées ; les autres événements uniquement lorsque cette option est activée. 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 leurs données de paiement (transactions PayU, remboursements, statuts de commande) ne sont jamais supprimées. Par défaut : désactivé.

Tunnel de commande

À l'étape de paiement, le client choisit l'option de paiement (par défaut PayU) et voit la description ainsi que la note Vous serez redirigé vers PayU pour finaliser le paiement (BLIK, virement bancaire, carte et autres moyens). Après confirmation, le module crée une commande PayU pour le total du panier dans la devise du panier, avec la description Cart #, le numéro de panier et le nom de votre boutique, ainsi que les produits, la livraison et l'emballage cadeau pour affichage sur la page PayU. L'e-mail, le nom et le téléphone du client sont transmis à PayU. La langue de la page PayU suit celle de la boutique lorsque PayU la prend en charge, sinon l'anglais est utilisé. Le client est redirigé vers la page PayU, y choisit un moyen de paiement et paie. À ce stade, aucune commande n'existe encore.

Chaque tentative de paiement reçoit sa propre commande PayU. Lorsque le client réessaie, le paiement PayU précédent resté inachevé pour le panier est annulé chez PayU, de sorte qu'un ancien lien de paiement ne peut pas être réglé deux fois. Si le paiement précédent s'avère déjà payé, la commande est créée au lieu d'un nouveau paiement.

Le retour sur votre boutique ne paie jamais une commande à lui seul. La commande n'est marquée payée qu'après confirmation de PayU : par une notification signée avec la Second Key de l'environnement du paiement, ou par une vérification côté serveur de l'état de la commande PayU lorsque le client revient (au plus une fois toutes les 10 secondes par panier). La commande PayU doit avoir été créée pour ce panier, et le montant et la devise doivent correspondre. Le module gère les statuts PayU suivants :

Après un paiement confirmé, le client voit la page standard de confirmation de commande. Pour une commande en attente de confirmation ou en attente de traitement, la page ajoute Votre paiement est en cours de vérification. Nous vous enverrons un e-mail dès qu'il sera confirmé. Si le paiement d'une telle commande est annulé par la suite, la page affiche Votre paiement PayU n'a pas abouti. Veuillez nous contacter au sujet de cette commande.

Si PayU n'a pas encore confirmé le paiement au retour du client, une page Payment confirmation affiche Nous n'avons pas encore reçu la confirmation de paiement de PayU. Si le paiement a été interrompu, vous pouvez réessayer : (ou, lorsque PayU a signalé une erreur, Le paiement n'a pas abouti. Vous pouvez réessayer :) avec les boutons Pay again et Check again. La notification crée la commande dès son arrivée. Si le paiement a été annulé, le client revient au tunnel de commande avec Le paiement n'a pas abouti. Vous pouvez réessayer ou choisir un autre moyen de paiement. Le panier est conservé.

Si PayU ne peut pas démarrer le paiement, le client reste dans le tunnel de commande avec Erreur de paiement. Veuillez réessayer ou choisir un autre moyen de paiement. La raison technique est écrite dans le journal. Si les clés du mode actif sont manquantes, le message est La passerelle de paiement n'est pas correctement configurée. Veuillez contacter l'administrateur.

Si un bon de réduction du panier cesse d'être valide entre le paiement et sa confirmation, il est retiré de la commande. La commande passe alors en PayU payment on hold avec une note mentionnant le bon, car le client a payé le prix avec la réduction.

Le client choisit le moyen de paiement sur la page PayU, et non dans votre tunnel de commande. Le module ne comporte aucun formulaire de carte dans votre boutique, ni cartes enregistrées ni paiement en un clic, ni abonnements, ni widgets de paiement échelonné ou de crédit PayU. Il utilise un seul point de vente par environnement.

Commandes et remboursements

Statuts de commande

Pas encore de commande : le client a été envoyé vers PayU et n'a pas payé, ou PayU n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : le paiement a été confirmé. Il est enregistré avec l'identifiant de commande PayU comme ID de transaction, et une note affiche l'identifiant de commande PayU, le montant et l'environnement (sandbox ou live).

Awaiting PayU payment confirmation : le paiement est autorisé et attend votre action (réception automatique désactivée ou échec de la réception). Aucun paiement n'est encore enregistré.

PayU payment on hold : le montant ou la devise payé ne correspondait pas au panier (la commande n'est pas marquée payée), un bon de réduction a été retiré, un paiement en attente de confirmation avait un autre montant, ou un paiement a été effectué pour une commande annulée (le paiement est enregistré). La note indique lequel. Vérifiez la commande et traitez-la ou remboursez le paiement.

Payment error : le paiement d'une commande en attente de confirmation a été annulé ou rejeté.

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

Chaque notification n'est traitée qu'une fois : les notifications répétées n'ajoutent pas de notes et ne modifient pas à nouveau la commande. Si un autre paiement est effectué pour une commande déjà payée ou remboursée, une note vous invite à le rembourser dans le panneau PayU. Un paiement en attente de confirmation sur une commande déjà payée ou clôturée est annulé automatiquement, afin que l'argent ne soit pas prélevé deux fois.

Bloc paiement PayU

La page de commande affiche un bloc PayU payment avec l'identifiant de commande PayU, l'extOrderId, le statut PayU, le montant payé et remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les PayU notes de la commande. Les actions du bloc nécessitent le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire.

Paiements en attente de confirmation

Pour une commande dont le paiement attend une confirmation, le bloc affiche Receive PayU payment (waiting for confirmation) et Cancel PayU payment (release the funds). Une fois la question confirmée, l'action est envoyée à PayU avec les clés de l'environnement du paiement, ajoutée aux notes avec votre nom, et le nouveau statut PayU est appliqué immédiatement : un paiement réceptionné place la commande en Payment accepted, un paiement annulé en Payment error.

Remboursements

Dans le bloc PayU payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via PayU. Confirmez la question Rembourser ce montant via PayU ? Cette action est irréversible. Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé pour la commande PayU qui a réellement été payée, avec les clés de l'environnement du paiement ; ces clés doivent donc être renseignées. Les remboursements sont effectués dans le montant et la devise débités par PayU : après un écart de montant ou de devise, vous pouvez rembourser jusqu'au montant réellement payé par le client, et non jusqu'au total de la commande. Le motif est envoyé comme description du remboursement. Si PayU refuse le remboursement, le bloc affiche l'erreur de PayU et aucun remboursement n'est enregistré. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut.

Les remboursements sont asynchrones chez PayU. Le module ajoute immédiatement une note avec l'identifiant et le statut du remboursement PayU ; le statut final arrive plus tard sous forme de notification PayU et est ajouté aux notes et à l'historique des remboursements. Si PayU annule un remboursement, la note indique que l'argent n'a pas été restitué au client, et le montant peut être remboursé à nouveau.

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

Clé de licence

Le module fonctionne avec une clé de licence VibeFox achetée sur vibefox.net. Le bloc de licence License — VibeFox PayU Payment est le premier bloc de la page Modules > Module Manager > VibeFox PayU 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, 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 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 n'est pas affiché aux clients dans le tunnel 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 dans le tunnel 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 par les notifications, 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 n'apparaît pas dans le tunnel de commande : vérifiez que la licence est active, que Enable/Disable est activé et que les quatre clés du mode actif sont renseignées : les clés Sandbox en mode sandbox, les clés Live en mode live. Vérifiez que la devise du panier fait partie des devises prises en charge. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client. La page de réglages affiche un avertissement lorsque des clés manquent ou que la devise de la boutique n'est pas prise en charge.

Le paiement a abouti, mais aucune commande n'a été créée : PayU n'a pas encore envoyé la notification, et la vérification d'état sur la page de retour n'a pas vu de paiement terminé. Vérifiez que la Notification URL affichée dans les réglages est accessible depuis Internet. Activez Logging pour voir ce qui arrive. Le client peut également cliquer sur Check again sur la page Payment confirmation.

La notification répond Invalid signature : la notification n'a pas été signée avec la Second Key de l'un ou l'autre environnement. Vérifiez Live Second Key (MD5) et Sandbox Second Key (MD5). La réponse Invalid signature for this payment signifie que la notification a été signée avec la clé de l'autre environnement que celui du paiement.

La notification répond Ignored: unknown PayU order : la commande PayU n'a pas été créée par cette boutique, par exemple une autre boutique sur le même POS. PayU cesse les nouvelles tentatives.

La notification répond Busy, retry later : le panier était en cours de confirmation par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). PayU renouvelle la notification. Activez Logging pour voir la raison.

La Notification URL affiche POST expected dans le navigateur : c'est normal. L'URL n'accepte que les notifications de PayU.

Le client voit Payment error en choisissant PayU : activez Logging et consultez le champ Log de la page du module. Le journal affiche le code HTTP et le statut PayU. Impossible de s'authentifier auprès de PayU (vérifiez le OAuth client ID / secret). signifie que les clés OAuth du mode actif sont erronées.

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

La commande est en Awaiting PayU payment confirmation : la réception automatique est désactivée pour votre point de vente et le paiement attend votre action. Utilisez Receive PayU payment ou Cancel PayU payment dans le bloc PayU.

Le remboursement échoue : Cette commande n'a pas de paiement PayU abouti. Impossible de traiter le remboursement. signifie que PayU n'a pas encore finalisé de paiement pour la commande. Un message indiquant que les clés Sandbox ou Live sont manquantes signifie que le paiement a été effectué dans cet environnement et que ses clés ne sont pas renseignées. Saisissez-les et réessayez.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PayU Payment et choisissez Uninstall. La clé de licence et l'état de la licence de ce module sont toujours supprimés. Les jetons d'accès PayU mis en cache sont toujours supprimés. Si Delete data on uninstall est activé, les réglages et le journal du module sont supprimés. Sinon, tous les réglages sont conservés pour une réinstallation ultérieure. Les transactions et remboursements PayU ainsi que les statuts de commande Awaiting PayU payment confirmation et PayU payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

PayU est une marque déposée de son titulaire respectif. Ce module n'est ni affilié à PayU ni approuvé par PayU.