VibeFox GoPay for WooCommerce — Aide
Prérequis
WordPress : 6.0 ou ultérieur.
WooCommerce : 7.6 ou ultérieur, installé et actif. L'extension refuse de s'activer sans lui.
PHP : 8.0 ou ultérieur.
Devise : GoPay accepte CZK, EUR, PLN, USD, GBP, HUF, RON et BGN. Avec une autre devise, le moyen de paiement est masqué sur la page de paiement.
Compte GoPay : vous avez besoin du GoID, du Client ID et du Client Secret de votre compte marchand GoPay. Vous les trouverez dans les réglages d'intégration du compte. Le compte sandbox (de test) possède ses propres identifiants. Aucune configuration des notifications n'est nécessaire dans le compte GoPay, mais votre boutique doit être accessible depuis Internet.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un 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 téléverser le dossier wcp_gopay_gateway vers /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > GoPay > Manage, ou cliquez sur Settings sous le nom de l'extension dans la page Plugins.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page, puis cliquez sur Activate.
5. Saisissez le GoID, le Client ID et le Client Secret sandbox, laissez Test Mode activé et activez Enable/Disable.
6. Passez une commande de test. Lorsque tout fonctionne, saisissez les identifiants de production et décochez Test Mode.
Configuration
Tous les réglages sont sur une seule page : WooCommerce > Settings > Payments > GoPay. Sous la description de la passerelle, la page affiche Sandbox mode — test payments only ou Production mode — real payments. Elle vous avertit si le GoID, le Client ID ou le Client Secret du mode actuel est manquant, ou si GoPay n'accepte pas la devise de la boutique. Dans les deux cas, GoPay n'est pas proposé sur la page de paiement. Dans la liste des moyens de paiement, la passerelle est signalée comme nécessitant une configuration tant que les identifiants du mode actuel ne sont pas renseignés. Lors de l'enregistrement, les jetons d'accès GoPay mis en cache sont supprimés afin que les nouveaux identifiants soient utilisés immédiatement.
Enable/Disable: Enable GoPay payment gateway active ou désactive le moyen de paiement. Par défaut : désactivé.
Title: titre du moyen de paiement affiché sur la page de paiement. Par défaut : GoPay.
Description: description du moyen de paiement affichée sur la page de 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 (réglages 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: Enable sandbox/test mode envoie les paiements à gw.sandbox.gopay.com avec les identifiants sandbox. Aucun argent réel n'est prélevé. Décochez cette option pour accepter des paiements réels avec les identifiants de production (gate.gopay.cz). Par défaut : activé.
Sandbox GoID: le GoID de votre compte GoPay sandbox (de test).
Sandbox Client ID: le Client ID OAuth du compte sandbox.
Sandbox Client Secret: le Client Secret OAuth du compte sandbox.
Production GoID: votre identifiant 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 conserve la valeur précédente.
Paiement
Payment Page Language: langue de la page de paiement GoPay. Par défaut : Automatic (site language, then billing country). Le mode automatique utilise la langue de votre site ; si GoPay ne la propose pas, c'est le pays de facturation qui décide, sinon l'anglais est utilisé. Vous pouvez également fixer l'une des 19 langues suivantes : tchèque, anglais, slovaque, allemand, polonais, hongrois, roumain, bulgare, croate, slovène, estonien, letton, lituanien, français, italien, espagnol, portugais, ukrainien ou russe.
Order Status After Payment: statut attribué à la commande lorsque le paiement est confirmé. Il est défini immédiatement, avec un seul changement de statut et un seul e-mail au client.
Notifications de paiement
La notification informe votre boutique qu'un paiement a été effectué. L'URL de notification est envoyée à GoPay avec chaque paiement ; aucune configuration n'est donc nécessaire dans le compte GoPay. Les réglages affichent cette URL. Elle ressemble à https://your-site/?gopay-api=gopay_payment_notification. Elle doit être accessible depuis Internet, sans protection par mot de passe, mode maintenance ni pare-feu devant elle.
Les notifications GoPay ne contiennent que l'identifiant du paiement et aucune signature. Chaque notification est vérifiée en demandant l'état du paiement à l'API GoPay ; le paiement doit aussi avoir été créé par l'extension pour une commande 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 confirmée que lorsque le client revient à la boutique après le paiement.
Avancé
Logging: Enable logging écrit les événements GoPay dans WooCommerce > Status > Logs, source wcp_gopay_gateway. Les erreurs sont toujours consignées. Les identifiants, jetons, données de carte, ainsi que l'adresse e-mail, le téléphone et l'adresse du client ne sont jamais consignés. Par défaut : désactivé.
Delete Data on Uninstall: Delete plugin settings, cached access tokens and log files when uninstalled. Lorsque cette option est activée, la suppression de l'extension efface les réglages de la passerelle, les jetons d'accès GoPay mis en cache et les journaux. Par défaut : désactivé.
Paiement
Le client choisit le moyen de paiement (par défaut GoPay) et passe la commande. L'extension crée un paiement GoPay du montant total de la commande dans sa devise, avec les articles, les frais de livraison et les frais supplémentaires, puis redirige le client vers la page de paiement GoPay. GoPay y propose les moyens activés sur votre compte, comme les cartes de paiement, Apple Pay, Google Pay et les virements bancaires. Le nom de facturation, l'adresse e-mail, le téléphone et l'adresse du client sont transmis à GoPay ; les champs vides ne sont pas envoyés. Chez GoPay, le paiement apparaît sous le nom Order, suivi du numéro de commande.
Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation par GoPay : par la notification ou par une requête à l'API GoPay lorsque le client revient. Si une notification et le retour arrivent au même moment, ils sont traités l'un après l'autre ; la commande n'est donc jamais finalisée deux fois. Une fois le paiement confirmé, le client arrive sur la page de confirmation de commande.
Si le paiement n'a pas été effectué, a été annulé ou a expiré, le client est dirigé vers la page Pay for order 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 client peut repayer une commande impayée depuis cette page. Si la commande est déjà payée, aucun second paiement GoPay n'est créé.
Si GoPay ne peut pas démarrer le paiement, le client voit un bref 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 ajoutée aux notes de commande.
Le moyen de paiement fonctionne sur la page de paiement classique, dans les blocs Cart et Checkout et sur la page Pay for order. En mode sandbox, le bloc Checkout affiche Sandbox mode: no real payment will be made. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).
Le client choisit le moyen de paiement sur la page GoPay ; il ne peut pas le choisir dans WooCommerce. L'extension 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 WooCommerce.
Commandes et remboursements
Statuts de commande
Pending payment: le client a été redirigé vers GoPay et n'a pas encore payé, ou GoPay n'a pas encore confirmé le paiement.
Processing or Completed: le paiement a été confirmé. Le statut suit Order Status After Payment. La note de commande indique l'identifiant du paiement GoPay et l'instrument de paiement. L'identifiant de transaction est celui du paiement GoPay.
On hold: GoPay a confirmé le paiement, mais le montant ou la devise diffère de ceux de la commande ; ou le paiement est arrivé après l'annulation de la commande ; ou le paiement est seulement préautorisé et les fonds ne sont pas encore capturés. La note de commande en explique la raison. Un paiement préautorisé doit être capturé dans GoPay, puis vous devez finaliser la commande manuellement.
Failed: le dernier paiement GoPay d'une commande impayée a été annulé ou a expiré.
Refunded: le paiement GoPay de la commande a été intégralement remboursé, par exemple depuis le compte GoPay.
Si une autre tentative de paiement d'une commande déjà payée est également réglée, la commande n'est pas modifiée. Une note vous demande de rembourser le doublon depuis 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 notification ultérieure ne rouvre jamais une commande payée que vous avez annulée ou remboursée.
Remboursements
Ouvrez la commande, cliquez sur Refund, saisissez le montant puis cliquez sur Refund via GoPay. Les remboursements totaux et partiels sont pris en charge. GoPay n'accepte les remboursements partiels que 24 heures après le paiement. Le remboursement est envoyé dans le mode utilisé pour le paiement (sandbox ou production) ; les identifiants de ce mode doivent donc être configurés. Si GoPay refuse le remboursement, WooCommerce affiche le message de GoPay et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande. Un remboursement que GoPay accepte pour traitement ultérieur est également indiqué comme accepté.
Les remboursements effectués dans le compte GoPay arrivent par notification. Un remboursement total fait passer la commande à « Remboursée » ; un remboursement partiel ajoute une note. Ils ne sont pas enregistrés automatiquement comme remboursements WooCommerce.
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 > GoPay. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date de validité de la licence et votre domaine. Cliquez sur Check now pour vérifier à nouveau le statut, sur Change key pour saisir une autre clé et sur Remove key pour la supprimer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.
Une clé fonctionne sur un domaine. Supprimer la clé d'un site ne libère pas son emplacement de domaine. Libérez cet emplacement dans votre compte vibefox.net.
Sans clé active, GoPay n'est pas affiché aux clients sur la page de paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les responsables de boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez 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.
À l'expiration d'une licence, l'extension continue de fonctionner, mais son renouvellement est nécessaire pour les mises à jour et l'assistance. Le statut est automatiquement vérifié à nouveau en arrière-plan.
Dépannage
GoPay n'apparaît pas sur la page de paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le GoID, le Client ID et le Client Secret du mode actuel sont renseignés et que la devise est CZK, EUR, PLN, USD, GBP, HUF, RON ou BGN. Sur la page Pay for order, c'est la devise de la commande qui compte. La page des réglages affiche un avertissement si les identifiants ou la devise sont incorrects.
Le paiement a été effectué, mais la commande reste Pending payment : GoPay n'a pas pu atteindre l'URL de notification indiquée dans les réglages et le client n'est pas revenu dans la boutique. Supprimez la protection par mot de passe, le mode maintenance ou les règles de pare-feu qui bloquent l'URL. Vérifiez que les identifiants du mode utilisé pour le paiement sont configurés, car chaque notification est vérifiée avec ceux-ci. Consultez WooCommerce > Status > Logs, source wcp_gopay_gateway. GoPay renvoie les notifications qui n'ont pas reçu de réponse positive.
La notification répond « Order not found » : le paiement n'a pas été créé par cette boutique ou la commande correspondante a été supprimée.
La notification répond « Payment state could not be verified » : l'API GoPay était inaccessible ou les identifiants de ce mode sont incorrects. GoPay renvoie la notification.
Le client voit une erreur en passant commande : ouvrez les notes de commande ou activez Logging. La note indique l'erreur GoPay. La cause habituelle est l'utilisation d'identifiants incorrects ou de ceux de l'autre mode. Un message concernant les coordonnées de facturation signifie que GoPay n'a pas accepté l'adresse e-mail, le téléphone ou l'adresse.
Les paiements de test ne confirment pas une commande réelle : les modes sandbox et production sont séparés. Chaque paiement est vérifié dans le mode où il a été créé. Réglez Test Mode sur le mode voulu et utilisez les identifiants correspondants.
La commande est On hold après le paiement : lisez la note de commande. Le montant ou la devise payés différaient de ceux de la commande, le paiement est arrivé après son annulation ou il est seulement préautorisé.
Le remboursement échoue : lisez le message de GoPay. Un remboursement partiel n'est possible que 24 heures après le paiement. Un message concernant le mode signifie que le paiement a été fait en sandbox ou en production et que les identifiants correspondants ne sont pas configurés.
Le bloc de licence affiche une erreur : suivez les indications 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é sur le nouveau domaine. Si le serveur de licences est inaccessible, l'extension continue de fonctionner avec le dernier statut connu.
Pour les développeurs : le filtre gopay_p_payment_payload modifie la requête de paiement et gopay_p_icon modifie l'icône du moyen de paiement.
Désinstallation
La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la depuis 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, les jetons d'accès mis en cache et les journaux ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les identifiants des paiements GoPay stockés dans les commandes sont toujours conservés. Les commandes existantes gardent leurs notes de paiement et leurs identifiants de transaction.
GoPay est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à GoPay ni approuvée par GoPay.