VibeFox PayPal 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.

Compte PayPal : un compte PayPal Business avec une application REST API dans le PayPal Developer Dashboard. Vous avez besoin du Client ID et du Secret de l'application. Les applications sandbox et live ont des identifiants différents. Aucun webhook n'est nécessaire : le module confirme chaque paiement sur votre serveur pendant que le client est sur la page de paiement.

Devise : l'une des devises prises en charge par PayPal : AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD ou USD.

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 PayPal 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, puis cliquez sur Activate (voir Clé de licence).

4. Dans le PayPal Developer Dashboard, créez une application REST API (sandbox et/ou live) et copiez son Client ID et son Secret.

5. Saisissez les identifiants du mode que vous utilisez, choisissez Capture ou Authorize, activez Enable/Disable et cliquez sur Save.

6. Testez avec un compte acheteur sandbox PayPal, puis désactivez Sandbox mode et saisissez les identifiants live.

À l'installation, le module crée trois statuts de commande : PayPal payment authorized, Awaiting PayPal payment et PayPal 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 le limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox PayPal Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit lorsque le moyen de paiement est activé mais que le Client ID ou le Secret du mode sélectionné est vide, et lorsque PayPal ne prend pas en charge la devise par défaut de la boutique. Dans les deux cas, le moyen de paiement est masqué sur la page de paiement. Tant que le mode sandbox est activé, la page affiche Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. L'enregistrement des réglages supprime les jetons d'accès PayPal mis en cache, afin que les nouveaux identifiants soient utilisés immédiatement.

General

Enable/Disable : Enable PayPal Gateway active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement que voient les clients sur la page de paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : PayPal. Obligatoire.

Description : le texte affiché sous le moyen de paiement sur la page de paiement. Par défaut : Pay with your PayPal account or a card via PayPal.

Identifiants API

Créez une application REST API dans le PayPal Developer Dashboard et copiez son Client ID et son Secret. La section contient des liens vers les applications sandbox et vers les applications live. Seuls les champs du mode sélectionné sont affichés ; les identifiants des deux modes restent enregistrés.

Sandbox mode : les paiements passent par le sandbox PayPal avec les identifiants sandbox ; aucun argent réel n'est déplacé. Par défaut : activé. Désactivez-le pour accepter des paiements réels. Les captures, annulations et remboursements utilisent toujours l'environnement dans lequel la commande a été payée. Tant qu'il est activé, les clients voient Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. sous le moyen de paiement.

Sandbox Client ID : le Client ID de votre application REST API sandbox.

Sandbox Secret : le Secret de votre application REST API sandbox.

Live Client ID : le Client ID de votre application REST API live.

Live Secret : le Secret de votre application REST API live.

Les secrets 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 secrets : cochez un secret puis cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Paiement

Payment action : ce qui se passe lorsque le client approuve le paiement. Par défaut : Capture.

Avancé

Debug log : enregistre les requêtes API dans logs/wc_plg_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, même lorsque ce commutateur est désactivé. Les identifiants, les jetons et les données de l'acheteur 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'il est activé, la désinstallation du module supprime les réglages du moyen de paiement, les jetons en cache et le journal. Les données de paiement des commandes (identifiants PayPal des commandes, remboursements) et les statuts de commande sont toujours conservés. Par défaut : désactivé.

Page de paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut PayPal) et le bouton PayPal apparaît à la place du formulaire de paiement. Un clic sur le bouton crée sur votre serveur une commande PayPal pour le total du panier, dans la devise du panier. Le montant est toujours calculé sur le serveur, jamais dans le navigateur. Aucune commande n'existe encore à ce stade.

Le client approuve le paiement dans la fenêtre PayPal avec un compte PayPal ou une autre source de financement proposée par PayPal. La page de paiement affiche alors PayPal payment approved. Completing your order… et passe la commande. Si les conditions générales de vente ne sont pas encore acceptées, la page de paiement affiche PayPal payment approved. Click "Place order" to complete it. Si le client clique sur Place order sans approuver de paiement, le message est Please click the PayPal button and approve the payment first.

Votre serveur lit ensuite la commande PayPal et vérifie qu'elle est approuvée, qu'elle a été créée pour ce panier, qu'elle n'est pas utilisée par un autre panier, et que son montant et sa devise correspondent au panier. Ce n'est qu'alors que le paiement est capturé (ou autorisé), que la commande est créée et que le client voit la page standard de confirmation de commande.

Si le total du panier a changé après l'approbation, rien n'est capturé. Le client voit The order total changed after you approved the payment in PayPal. Please click the PayPal button again to approve the new total. Si PayPal refuse le paiement, le client revient à l'étape de paiement et est invité à cliquer sur le bouton PayPal et à choisir un autre mode de paiement. Aucune commande n'est créée. Si le client ferme la fenêtre PayPal, la page de paiement affiche You cancelled the PayPal payment.

Si PayPal ne répond pas pendant la capture, le client voit We could not confirm your PayPal payment yet. Please try again in a moment — you will not be charged twice. L'approbation est conservée, y compris après un rechargement de la page, et Place order l'utilise à nouveau. Si PayPal avait finalisé la tentative précédente, ce paiement est utilisé et une nouvelle approbation n'est pas capturée. Si le paiement a été prélevé mais que la commande n'a pas pu être créée, le client voit Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. La tentative suivante crée la commande à partir du paiement enregistré, sans débiter à nouveau.

Le script PayPal n'est chargé que sur la page de paiement et dans son propre espace de noms, afin de ne pas entrer en conflit avec un autre module PayPal de la page. Le module fonctionne avec les thèmes Classic et Hummingbird.

Le module n'a pas de webhooks PayPal, de messages Pay Later, de champs de carte, ni de Venmo, Apple Pay, Google Pay ou Fastlane, ni de moyens de paiement enregistrés ou d'abonnements, ni de boutons sur les pages produit ou panier. Ce sont les adresses saisies dans la page de paiement PrestaShop qui sont utilisées, et non une adresse provenant de PayPal.

Commandes et remboursements

Statuts de commande

No order yet : le client n'a pas approuvé le paiement, ou PayPal l'a refusé. Seul le panier existe.

Payment accepted : la capture est terminée. La commande n'est marquée comme payée qu'après la confirmation de PayPal. Le paiement est enregistré avec l'identifiant de capture PayPal comme identifiant de transaction, et une note indique le montant, la commande PayPal et la capture.

PayPal payment authorized : le paiement a été autorisé et attend sa capture (action de paiement Authorize).

Awaiting PayPal payment : la capture est PENDING chez PayPal, par exemple en cours d'examen du paiement.

PayPal payment on hold : le montant ou la devise payé diffère de la commande, ou le paiement n'a pas pu être lu dans la réponse de PayPal. La note l'explique. Lorsque PayPal a débité dans la devise de la commande, le montant réellement payé est enregistré comme paiement. Vérifiez la commande et traitez-la, ou remboursez le paiement.

Canceled : l'autorisation a été annulée avec Void PayPal authorization.

Payment error : une capture en attente a été refusée ou a échoué.

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

Si un second paiement arrive pour un panier qui a déjà une commande, la commande n'est pas modifiée. Une note vous invite à le vérifier dans votre compte PayPal et à le rembourser.

Bloc de paiement PayPal

La page de la commande affiche un bloc PayPal payment avec l'identifiant de commande PayPal et l'intention, l'identifiant de capture (lié au paiement dans votre compte PayPal, sandbox ou live), l'identifiant d'autorisation, le statut du paiement, le montant, les montants payé et remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les PayPal notes de la commande. Les boutons du bloc requièrent le droit de modifier les commandes, mais pas l'accès aux pages des modules. Le résultat de chaque action s'affiche dans le bloc.

Remboursements

Dans le bloc PayPal payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via PayPal. Confirmez la question Refund this amount through PayPal? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Le motif est transmis à PayPal comme note à l'acheteur. Les remboursements sont effectués dans le montant et la devise débités par PayPal ; ainsi, après un écart de montant ou de devise, vous pouvez rembourser jusqu'à la somme que le client a réellement payée, et non le total de la commande. Le remboursement est envoyé à l'environnement PayPal dans lequel le paiement a été effectué (sandbox ou live), donc les identifiants de cet environnement doivent être renseignés. Si PayPal n'accepte pas 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 et le statut du remboursement PayPal ; un remboursement PENDING est finalisé plus tard par PayPal. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut.

Un paiement uniquement autorisé ne peut pas être remboursé : utilisez Void PayPal authorization à la place. Le module ne crée pas d'avoirs. Les boutons standard de remboursement de PrestaShop sur la page de la commande ne renvoient pas d'argent via PayPal. Les remboursements, litiges et annulations effectués dans votre compte PayPal ne sont pas synchronisés avec PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox PayPal Gateway est le premier bloc de la page Modules > Module Manager > VibeFox PayPal 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. Sous ces boutons figurent la ligne Product: presta-payment-paypal et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant du droit 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, PayPal n'est pas affiché aux clients sur la page de paiement. Si un paiement est tout de même lancé, la boutique refuse de créer la commande PayPal et le client voit An error occurred during PayPal checkout. Please try again. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office ; le mode de paiement est donc masqué pour vous aussi : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester sur la page de paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les remboursements et les actions du bloc PayPal continuent de fonctionner.

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

Dépannage

PayPal does not appear at checkout : vérifiez que la licence est active, que Enable/Disable est activé, que le Client ID et le Secret du mode sélectionné sont renseignés, que la devise du panier est prise en charge par PayPal et que le total du panier est supérieur à zéro. La page des réglages affiche un avertissement lorsque les identifiants ou la devise posent problème. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client. Une extension de navigateur qui bloque www.paypal.com masque également le bouton.

The payment went through, but no order was created : le module n'a pas de webhook, donc le paiement n'est confirmé que pendant la page de paiement. Cela arrive lorsque PayPal n'a pas répondu pendant la capture ou que la commande n'a pas pu être créée. Activez Debug log et consultez le champ Log, vérifiez le paiement dans votre compte PayPal, ou laissez le client réessayer : une nouvelle tentative ne débite jamais deux fois et crée la commande à partir du paiement enregistré.

PayPal could not be loaded : le script PayPal ne s'est pas chargé dans le navigateur, par exemple à cause d'un bloqueur ou d'un problème réseau.

PayPal is not available right now : les identifiants sont erronés ou appartiennent à l'autre mode. Copiez à nouveau le Client ID et le Secret de la bonne application.

Your PayPal approval could not be matched to this checkout : la commande PayPal n'a pas été créée pour ce panier, par exemple après l'expiration de la session. Le client clique à nouveau sur le bouton PayPal.

This payment is already being processed : le même panier a été soumis deux fois au même moment. Le client attend un instant et vérifie l'e-mail avant de réessayer.

The order is on hold after payment : lisez les notes du bloc PayPal payment. Le paiement a été autorisé (capturez-le avec Capture PayPal payment), la capture est PENDING chez PayPal (utilisez Check PayPal payment status plus tard), ou le montant ou la devise payé ne correspondait pas à la commande (traitez la commande ou remboursez ce qui a été payé).

Capture of an authorization fails : l'autorisation peut dater de plus de 29 jours ou avoir déjà été annulée. Le bloc et les notes affichent l'erreur PayPal.

Refund fails : la commande n'a pas de capture PayPal (seulement une autorisation), le montant dépasse ce qui reste à rembourser, ou les identifiants de l'environnement dans lequel le paiement a été effectué sont absents. Le bloc indique lequel de ces cas s'applique.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PayPal 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 moyen de paiement, les jetons d'accès PayPal 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 transactions et remboursements PayPal ainsi que les statuts de commande PayPal payment authorized, Awaiting PayPal payment et PayPal 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.

PayPal est une marque commerciale de son propriétaire respectif. Ce module n'est ni affilié à PayPal ni approuvé par PayPal.