VibeFox GoPay 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 : GoPay accepte CZK, EUR, PLN, USD, GBP, HUF, RON et BGN. Avec une autre devise de panier, le moyen de paiement est masqué lors du paiement.
Compte GoPay : vous avez besoin du GoID, du Client ID et du Client Secret de votre compte marchand GoPay. Ils figurent dans les paramètres d'intégration du compte. Le compte sandbox (de test) possède ses propres identifiants. Rien n'a besoin d'être configuré dans le compte GoPay pour les notifications, mais votre boutique doit être accessible depuis Internet.
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 GoPay Gateway 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 le GoID, le Client ID et le Client Secret du sandbox, laissez Test Mode activé, activez Enable/Disable et cliquez sur Save.
5. Passez une commande test. Lorsque tout fonctionne, saisissez les identifiants de production et désactivez Test Mode.
À l'installation, le module crée le statut de commande GoPay payment on hold. PrestaShop propose le 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 GoPay Gateway > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Sandbox mode — test payments only ou Production mode — real payments. Elle vous avertit lorsque le GoID, le Client ID ou le Client Secret du mode actuel est absent, ainsi que lorsque GoPay n'accepte pas la devise par défaut de la boutique. Dans les deux cas, GoPay n'est pas proposé lors du paiement. Lors de l'enregistrement, les jetons d'accès GoPay mis en cache sont effacés, de sorte que les nouveaux identifiants sont utilisés immédiatement.
GoPay
Enable/Disable : Enable GoPay payment gateway active ou désactive le moyen de paiement. Par défaut : désactivé.
Title : le titre du moyen de paiement affiché lors du paiement. Il correspond également au nom du moyen de paiement enregistré dans la commande. Par défaut : GoPay. Obligatoire : un titre vide n'est pas enregistré.
Description : la description du moyen de paiement affichée lors du paiement. Par défaut : Pay securely via GoPay - cards, wallets, bank transfers.
Identifiants API
Le GoID, le Client ID et le Client Secret sont affichés dans votre compte marchand GoPay (paramètres d'intégration). Le compte sandbox (de test) possède ses propres identifiants. La documentation de l'API se trouve sur doc.gopay.com.
Test Mode : envoie les paiements vers gw.sandbox.gopay.com avec les identifiants sandbox. Aucun argent réel n'est débité. Désactivez-le pour accepter de vrais paiements avec les identifiants de production. Par défaut : activé.
Sandbox GoID : le GoID de votre compte sandbox (de test) GoPay.
Sandbox Client ID : le Client ID OAuth du compte sandbox.
Sandbox Client Secret : le Client Secret OAuth du compte sandbox.
Production GoID : votre identifiant de marchand GoPay (GoID).
Production Client ID : le Client ID OAuth fourni par GoPay.
Production Client Secret : le Client Secret OAuth fourni par GoPay.
Un GoID ne contient que des chiffres, par exemple 8123456789. Si vous saisissez autre chose, la page affiche une erreur et la valeur précédente est conservée.
Les Client Secret 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 pour la modifier.
Clear saved client secrets : cochez la case et cliquez sur Save pour supprimer les deux Client Secret enregistrés. Un champ vide conserve la valeur enregistrée.
Paiement
Payment Page Language : la langue de la page de paiement GoPay. Par défaut : Automatic (site language, then billing country). L'option automatique utilise la langue du panier du client ; si GoPay ne la propose pas, le pays de facturation décide, et l'anglais est utilisé sinon. Vous pouvez aussi fixer l'une des 19 langues suivantes : Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian ou Russian.
Order Status After Payment : le statut de commande attribué lorsque le paiement est confirmé.
Les paiements qui ne correspondent pas à la commande, les paiements effectués après une annulation et les paiements préautorisés passent toujours en GoPay payment on hold.
Notifications de paiement
La notification indique à votre boutique qu'un paiement a été effectué. L'Notification URL est affichée dans cette section et envoyée à GoPay avec chaque paiement ; rien n'a donc besoin d'être configuré dans le compte GoPay. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_gopay_gateway/webhook, éventuellement avec un code de langue tel que /en/. Elle doit être accessible depuis Internet : aucune protection par mot de passe ni pare-feu devant elle. Elle fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique.
Les notifications GoPay ne contiennent que l'identifiant du paiement, sans signature. Chaque notification est vérifiée en demandant à l'API GoPay l'état du paiement, avec les identifiants du mode dans lequel le paiement a été effectué, et le paiement doit être un paiement créé par le module pour un panier de votre boutique. Si l'état ne peut pas être lu auprès de GoPay, votre boutique répond par une erreur et GoPay renvoie la notification. Sans notifications, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé.
Avancé
Logging : écrit les événements GoPay dans logs/gopay_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et les avertissements sont toujours journalisés. Les identifiants, les jetons, les données de carte ainsi que l'e-mail et le nom du client ne sont jamais journalisé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 : lorsqu'elle est activée, la désinstallation du module supprime les réglages du module, les jetons d'accès GoPay mis en cache et le journal. Les commandes, leurs données de paiement GoPay et le statut de commande GoPay payment on hold sont toujours conservés. Par défaut : désactivé.
Paiement
À l'étape de paiement, le client choisit le moyen de paiement (par défaut GoPay) et confirme. Le module crée un paiement GoPay pour le total du panier dans la devise du panier, avec les produits, la livraison et l'emballage cadeau, et envoie le client sur la page de paiement GoPay. Là, GoPay propose les moyens de paiement activés sur votre compte GoPay, comme les cartes de paiement, les virements bancaires et les portefeuilles électroniques. Le nom de facturation, l'e-mail, le téléphone et l'adresse du client sont transmis à GoPay ; les champs vides ne sont pas envoyés. Le paiement apparaît chez GoPay sous la forme Order PS- suivi du numéro du panier. Aucune commande n'existe encore à ce stade.
Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'une fois GoPay l'a confirmée : par la notification ou par une requête à l'API GoPay lors du retour du client. Une notification et un retour qui arrivent au même moment sont traités l'un après l'autre, de sorte qu'une seule commande est créée. Le client voit ensuite la page standard de confirmation de commande. Si la commande est passée en GoPay payment on hold, la page ajoute le message Your payment is being reviewed. We will contact you if anything else is needed.
Si GoPay n'a pas encore confirmé le paiement au moment où le client revient (par exemple, un virement bancaire est en cours, ou GoPay est injoignable), une page Payment confirmation affiche GoPay has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. avec un bouton Check again.
Si le paiement n'a pas été finalisé, a été annulé ou a expiré, le client revient au paiement avec le message The GoPay payment was not completed. You can try again or choose another payment method. ou The GoPay payment was cancelled or has expired. You can try again or choose another payment method. Le panier est conservé, et une nouvelle tentative crée un nouveau paiement GoPay. Un panier qui a déjà une commande n'est jamais débité à nouveau.
Si GoPay ne peut pas démarrer le paiement, le client reste sur la page de paiement avec un court message, par exemple GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. ou GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. La raison technique est écrite dans le journal.
Le client choisit le moyen de paiement sur la page GoPay ; il ne peut pas être choisi dans PrestaShop. Le module ne gère ni les abonnements ni les paiements récurrents, ni les cartes enregistrées, ni le formulaire de paiement intégré, ni la capture ou l'annulation de préautorisations depuis PrestaShop.
Commandes et remboursements
Statuts de commande
No order yet : le client a été envoyé vers GoPay et n'a pas payé, ou GoPay n'a pas encore confirmé le paiement. Seul le panier existe.
Payment accepted or Delivered : le paiement a été confirmé. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de paiement GoPay comme identifiant de transaction, et une note indique l'identifiant du paiement et le moyen de paiement.
GoPay payment on hold : GoPay a confirmé le paiement, mais le montant, la devise ou le numéro de commande diffère du panier (par exemple, le panier a été modifié après le début du paiement) ; ou le paiement est arrivé après l'annulation de la commande ; ou le paiement n'est que préautorisé et l'argent n'est pas encore capturé. La note l'explique. Un paiement préautorisé doit être capturé dans GoPay ; la commande passe alors au statut payé lorsque GoPay signale le paiement comme effectué.
Refunded : le paiement GoPay de la commande a été entièrement remboursé, par le module ou dans le compte GoPay.
Si une autre tentative de paiement d'une commande déjà payée est également payée, la commande n'est pas modifiée. Une note vous invite à rembourser le doublon dans le compte GoPay. Une note similaire est ajoutée lorsqu'un paiement GoPay est effectué pour une commande déjà marquée comme payée sans GoPay, par exemple manuellement. Une commande annulée ou remboursée n'est jamais rouverte par une notification ultérieure.
Bloc de paiement GoPay
La page de commande affiche un bloc GoPay payment avec l'identifiant du paiement GoPay, l'état GoPay et le moyen de paiement, le montant du paiement, les montants payé et remboursé, un badge Sandbox pour les paiements sandbox, le motif d'un contrôle manuel, l'historique des remboursements et les GoPay notes de la commande.
Remboursements
Dans le bloc GoPay payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via GoPay. Confirmez la question Refund this amount through GoPay? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. GoPay n'accepte les remboursements partiels que dans les 24 heures suivant le paiement. Les remboursements sont effectués au montant et dans la devise débités par GoPay : après un écart de montant ou de devise, vous pouvez donc rembourser à hauteur de ce que le client a effectivement payé. Le remboursement est envoyé dans le mode où le paiement a été effectué (sandbox ou production), les identifiants de ce mode doivent donc être renseignés. Si GoPay refuse le remboursement, le bloc affiche le message de GoPay et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes ; un remboursement accepté par GoPay pour un traitement ultérieur est noté comme accepté. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne modifie pas le statut.
Le module ne crée pas d'avoirs (credit slips). Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via GoPay.
Les remboursements effectués dans le compte GoPay arrivent par notification. Un remboursement total passe la commande en Refunded ; un remboursement partiel ajoute une note. Ils ne sont pas ajoutés à l'historique des remboursements du bloc.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox GoPay Gateway est le premier bloc de Modules > Module Manager > VibeFox GoPay 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, 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-gopay 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 statut 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, GoPay n'est pas affiché aux clients lors 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, donc le moyen de paiement vous est aussi masqué : vous pouvez configurer le module avant d'acheter une clé, mais ne pas le tester lors du paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas concernées : les paiements déjà lancés sont toujours confirmés, et les 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é à nouveau automatiquement pendant que vous travaillez 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
GoPay n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le mode actuel dispose de son GoID, de son Client ID et de son Client Secret, et que la devise du panier est l'une de CZK, EUR, PLN, USD, GBP, HUF, RON ou BGN. La page des réglages affiche un avertissement lorsque les identifiants manquent. 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 : GoPay n'a pas pu atteindre la Notification URL affichée dans les réglages, et le client n'est pas revenu dans la boutique. Supprimez la protection par mot de passe ou les règles de pare-feu qui bloquent l'URL. Vérifiez que les identifiants du mode dans lequel le paiement a été effectué sont renseignés, car chaque notification est vérifiée avec eux. Activez Logging et consultez le champ Log. GoPay renvoie les notifications qui n'ont pas reçu de réponse positive.
Notification answers Order not found : le paiement n'a pas été créé par cette boutique, ou son panier a été supprimé.
Notification answers Payment state could not be verified : l'API GoPay est injoignable, ou les identifiants de ce mode sont absents ou incorrects. GoPay renvoie la notification.
Notification answers Busy, retry later : le panier était en cours de traitement 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é). GoPay renvoie la notification. Activez Logging pour connaître la raison.
Le client voit une erreur lorsqu'il choisit GoPay : activez Logging et consultez le champ Log. Des identifiants incorrects, ou ceux de l'autre mode, sont la cause habituelle. Un message concernant les données de facturation signifie que GoPay n'a pas accepté l'e-mail, le téléphone ou l'adresse.
Les paiements de test ne confirment pas une commande réelle : sandbox et production sont séparés. Chaque paiement est vérifié dans le mode où il a été créé. Basculez Test Mode sur le mode souhaité et utilisez les identifiants de ce mode.
La commande est en GoPay payment on hold après le paiement : lisez les notes du bloc GoPay payment. Le montant ou la devise payé(e) ne correspondait pas au panier, le paiement est arrivé après l'annulation de la commande, ou le paiement n'est que préautorisé.
Le remboursement échoue : lisez le message de GoPay dans le bloc. Un remboursement partiel n'est possible que dans les 24 heures suivant le paiement. Un message concernant le mode signifie que le paiement a été effectué en mode sandbox ou production et que les identifiants de ce mode ne sont pas renseignés.
Pour les développeurs : le hook actionGopayPaymentPayload modifie la requête de paiement avant son envoi à GoPay.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox GoPay Gateway et choisissez Uninstall. La clé de licence et le statut de la licence de ce module sont toujours supprimés. Si Delete Data on Uninstall est activé, les réglages du module, les jetons d'accès GoPay mis en cache 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 données de paiement GoPay des commandes et le statut de commande GoPay 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 identifiants de transaction.
GoPay est une marque de son propriétaire respectif. Ce module n'est ni affilié à GoPay ni approuvé par GoPay.