VibeFox PayPlug 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 plus anciennes de PHP.

Devise et montants : euro (EUR), de 0,99 à 20 000,00 par paiement, les valeurs par défaut de PayPlug. Avec une autre devise de panier ou en dehors de ces limites, le mode de paiement est masqué.

Compte PayPlug : vous avez besoin des clés secrètes de votre compte PayPlug : la clé de test (sk_test_...) et/ou la clé de production (sk_live_...). Aucune autre clé n'est nécessaire, et aucune notification ne doit être configurée dans PayPlug. Votre boutique doit être accessible depuis Internet pour recevoir les notifications ; sinon, les commandes sont créées lorsque le client revient de PayPlug.

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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox PayPlug Gateway dans la liste des modules et cliquez sur Configure.

3. Collez 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. Collez vos clés secrètes depuis le portail PayPlug (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Testez un paiement avec Test Mode activé, puis désactivez-le pour accepter de vrais paiements.

À l'installation, le module crée le statut de commande PayPlug payment on hold. PrestaShop active 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 PayPlug Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque le mode de paiement est activé mais que la clé secrète du mode actuel est vide, et lorsque la devise par défaut de la boutique n'est pas l'euro. Dans les deux cas, le mode de paiement est masqué au moment du paiement.

Paiement

Enable/Disable : Enable PayPlug Gateway active ou désactive le mode de paiement. Par défaut : off.

Title : le nom du mode de paiement que voit le client au moment du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : PayPlug. Obligatoire.

Description : le texte affiché sous le mode de paiement au moment du paiement. Par défaut : Pay securely by card via PayPlug.

Clés API

Retrouvez vos clés secrètes dans le portail PayPlug, sous Developers > API keys. La section contient un lien vers le portail.

Test Mode : utilise la clé secrète de test pour les nouveaux paiements. Aucun paiement réel n'est traité. Les paiements effectués dans l'autre mode continuent d'utiliser la clé de leur propre mode pour les vérifications de statut et les remboursements. Par défaut : on. Tant qu'il est activé, les clients voient Test mode: no real payment will be made. sous le mode de paiement.

Test Secret Key : votre clé secrète de test PayPlug. Elle commence par sk_test_.

Live Secret Key : votre clé secrète de production PayPlug. Elle commence par sk_live_.

Une clé avec un mauvais préfixe n'est pas enregistrée. La page affiche par exemple Test Secret Key must start with "sk_test_". The previous value was kept. Les clés enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement si vous voulez la modifier.

Clear saved keys : cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Notification URL : l'adresse que le module envoie à PayPlug avec chaque paiement. Avec les URL simplifiées, elle ressemble à https://your-shop/module/wcp_payplug_gateway/webhook. Rien n'est à saisir dans le portail PayPlug. L'URL doit être accessible depuis Internet ; sinon, les commandes sont créées lorsque le client revient de PayPlug.

Commandes

Order Status After Payment : le statut de commande appliqué après un paiement réussi. Le statut est appliqué immédiatement, sans second changement de statut.

Avancé

Logging : enregistre les appels à l'API et les notifications dans logs/ppg_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 enregistrés. Les clés secrètes, les données de carte et les données clients ne sont jamais enregistrées. Par défaut : off.

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, les réglages du module et son journal sont supprimés à la désinstallation du module. Les identifiants de paiement PayPlug enregistrés avec les commandes et le statut de commande PayPlug payment on hold sont conservés. Par défaut : off.

Paiement

À l'étape du paiement, le client choisit le mode de paiement (par défaut PayPlug, avec le logo PayPlug). En mode test, l'option affiche Test mode: no real payment will be made. Après confirmation, le module crée un paiement PayPlug pour le total du panier en centimes et envoie le client sur la page de paiement PayPlug. Les adresses de facturation et de livraison, l'adresse e-mail et la langue du panier sont transmises à PayPlug. Le client y paie par carte. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée comme payée qu'après confirmation par PayPlug : le module lit le paiement depuis l'API PayPlug lorsque la notification arrive et lorsque le client revient. La commande est alors créée et le client voit la page standard de confirmation de commande avec le message Your payment with PayPlug has been received. Si la commande est en attente, la page indique We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Si la commande est en Payment error ou a été annulée sans paiement, la page indique Your PayPlug payment was not completed. Please contact us about this order. Si PayPlug n'a pas pu être interrogé au retour du client, une page Payment confirmation affiche le même texte « we are confirming » et un bouton Check again ; la notification crée la commande dès son arrivée.

Si le client annule sur la page PayPlug, la page de paiement est fermée chez PayPlug, de sorte qu'elle ne peut pas être payée plus tard par erreur. Le client revient au paiement avec un message : You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. ou, si le paiement est resté ouvert, Your PayPlug payment was not completed. You can try again or choose another payment method. Le panier est conservé.

Lorsque le client paie à nouveau le même panier, le module examine d'abord la tentative précédente. Si elle a été payée entre-temps, la commande est créée sans nouveau paiement. Si elle est toujours ouverte pour le même montant, la même page de paiement est réutilisée. Sinon, l'ancienne page est fermée chez PayPlug et un nouveau paiement est créé.

Si PayPlug ne peut pas démarrer le paiement, le client reste au moment du paiement avec un bref message, par exemple PayPlug could not accept your billing details (postcode). Please check them and try again. ou The payment provider could not be reached. Please try again in a moment. La raison technique est écrite dans le journal.

La notification fonctionne lorsque la boutique est en mode maintenance et n'est pas bloquée par la restriction par pays de votre boutique.

Les paiements sont capturés immédiatement. Le module ne propose ni paiement en plusieurs fois Oney, ni cartes enregistrées en un clic, ni formulaire de paiement intégré, ni abonnements, ni capture différée.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé chez PayPlug et n'a pas payé, ou PayPlug 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 PayPlug (pay_...) comme identifiant de transaction, et une note indique le paiement PayPlug et son mode.

PayPlug payment on hold : le montant payé ou la devise diffère du panier (note amount/currency mismatch, par exemple si le panier a été modifié après le début du paiement) ; ou un paiement de test a été effectué alors que la boutique était en mode production, de sorte qu'aucun argent n'a été reçu et qu'aucun paiement n'est enregistré ; ou le paiement est arrivé pour une commande qui avait été annulée ; ou un paiement est autorisé mais non capturé (capturez-le dans le portail PayPlug ; la commande est marquée comme payée lorsque PayPlug indique qu'il est payé). La note explique ce qu'il faut vérifier.

Payment error : un paiement autorisé d'une commande en attente a échoué ou a été annulé.

Refunded : le paiement a été intégralement remboursé via le module.

Si une seconde tentative sur un panier déjà payé est également payée, la commande n'est pas modifiée. Une note vous demande de rembourser le paiement en double dans le portail PayPlug. Une commande payée, annulée ou remboursée n'est jamais rouverte par une notification ultérieure.

Bloc paiement PayPlug

La page de commande affiche un bloc PayPlug payment avec l'identifiant de paiement PayPlug, le statut du paiement, le montant payé et remboursé, un badge Test mode pour les paiements de test, l'historique des remboursements et les PayPlug notes de la commande.

Remboursements

Dans le bloc PayPlug payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via PayPlug. Confirmez la question Refund this amount through PayPlug? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous avez besoin du droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Les remboursements sont effectués dans la limite du montant réellement débité par PayPlug : après un écart de montant, vous pouvez donc rembourser ce que le client a payé, et non le total de la commande. Le remboursement est adressé au paiement qui a réellement réglé la commande, avec la clé secrète du mode (test ou production) dans lequel il a été effectué ; cette clé doit donc être configurée. Si PayPlug refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant de remboursement PayPlug et le motif. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements ne sont disponibles qu'une fois que PayPlug a indiqué le paiement comme payé.

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

Les remboursements effectués dans le portail PayPlug arrivent par notification et sont ajoutés aux notes une seule fois. Ils ne sont pas comptabilisés dans le bloc et ne modifient ni le statut de la commande ni les avoirs. Enregistrez-les manuellement si nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox PayPlug Gateway est le premier bloc de Modules > Module Manager > VibeFox PayPlug Gateway > Configure, au-dessus des réglages. Collez 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) et les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour supprimer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-payplug et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission 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, PayPlug n'est pas proposé aux clients au moment 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 ne sait pas que vous êtes connecté au back-office, de sorte que le mode de paiement est également masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du paiement. 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 expire, le module continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié automatiquement pendant votre travail 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

PayPlug n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le mode actuel dispose d'une clé secrète (Test Secret Key en mode test, Live Secret Key en mode production), que la devise du panier est l'EUR et que le total du panier est compris entre 0,99 et 20 000,00 EUR. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client. Les développeurs peuvent modifier les devises et les limites avec les hooks actionWcpPayplugSupportedCurrencies et actionWcpPayplugAmountLimits (valeurs en centimes).

Le paiement a été effectué, mais aucune commande n'a été créée : la notification n'a pas atteint votre boutique et le client n'est pas revenu. Vérifiez que votre boutique est accessible depuis Internet à l'adresse Notification URL indiquée dans les réglages, par exemple qu'aucun pare-feu ni aucune protection par mot de passe ne la bloque. Activez Logging et consultez le champ Log pour repérer les notifications rejetées.

La notification répond Verification failed. : le paiement n'a pas pu être lu depuis l'API PayPlug, par exemple parce que PayPlug n'a pas répondu ou que la clé secrète du mode du paiement n'est pas renseignée. La commande n'est pas modifiée, et PayPlug renvoie la notification.

La notification répond Temporarily unavailable. : le panier était en cours de mise à jour par une autre requête au même moment, par exemple le retour du client, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). PayPlug renvoie la notification. Le journal indique la raison.

La notification répond Unknown payment. ou Payment does not belong to the order. : le paiement n'a pas été créé par cette boutique ou pour ce panier, par exemple un paiement d'une autre boutique sur le même compte PayPlug. Il est ignoré.

L'URL de notification affiche Method not allowed. dans le navigateur : c'est normal. L'URL n'accepte que les requêtes de PayPlug.

Le client voit une erreur en choisissant PayPlug : activez Logging et consultez le champ Log. Une mauvaise clé affiche This payment method is temporarily unavailable. Please choose another payment method. ; les autres messages nomment le champ de facturation que PayPlug a refusé.

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

Le remboursement échoue avec un message sur le mode : le paiement a été effectué en mode test ou production, et la clé secrète de ce mode n'est pas configurée. Saisissez-la et réessayez.

Le remboursement échoue avec Unexpected response from PayPlug. : PayPlug a répondu sans remboursement valide. Rien n'a été enregistré. Vérifiez le remboursement dans le portail PayPlug avant de réessayer.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PayPlug Gateway et choisissez Uninstall. La clé de licence et le statut de 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. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les enregistrements de paiements et de remboursements PayPlug ainsi que le statut de commande PayPlug 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.

PayPlug est une marque déposée de son propriétaire. Ce module n'est ni affilié à PayPlug ni approuvé par PayPlug.