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

Compte Stripe : vous avez besoin des clés API secrètes de votre compte Stripe et d'un point de terminaison de webhook dans le Stripe Dashboard (voir Configuration). Seules les clés secrètes et les secrets de signature des webhooks sont utilisés. Les clés publiables (pk_...) ne sont pas nécessaires, car Stripe Checkout est une page hébergée par Stripe.

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 Stripe 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. Collez vos clés secrètes Stripe, configurez le webhook dans le Stripe Dashboard et collez ses secrets de signature (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Testez un paiement en mode test avec la carte 4242 4242 4242 4242, puis désactivez Test Mode.

À l'installation, le module crée deux statuts de commande : Awaiting Stripe payment et Stripe 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 restreindre ces réglages dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Stripe Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit lorsque le mode actuel n'a pas de clé secrète (le mode de paiement est alors masqué à la commande) ou de secret de signature de webhook (les commandes ne sont alors confirmées que lorsque le client revient dans la boutique). Elle affiche aussi Le mode test est activé : aucun paiement réel n'est prélevé. tant que le mode test est activé.

Stripe Checkout

Enable/Disable : Enable Stripe Gateway active ou désactive le mode de paiement. Default: off.

Title : le nom du mode de paiement que voient les clients lors du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Default: Stripe. Obligatoire.

Description : le texte affiché sous le mode de paiement lors du paiement. Default: Pay securely with your credit or debit card via Stripe.

Clés API

Copiez les clés secrètes depuis Stripe Dashboard > Developers > API keys. Les clés de test et les clés réelles sont distinctes. Le mode test n'utilise que les clés de test, le mode réel uniquement les clés réelles. À l'enregistrement, le module vous avertit si une valeur ne commence pas par le préfixe attendu, par exemple si une clé publiable a été collée à la place d'une clé secrète.

Test Mode : utilise les clés de test Stripe. Aucun argent réel n'est prélevé ; payez avec des cartes de test Stripe comme 4242 4242 4242 4242. Default: on. Désactivez-le pour encaisser de vrais paiements. Tant qu'il est activé, les clients voient Mode test : aucun paiement réel n'est effectué. sous le mode de paiement.

Test Secret Key : la clé secrète du mode test. Elle commence par sk_test_ (ou rk_test_ pour une clé restreinte).

Test Webhook Secret : le secret de signature (whsec_...) du point de terminaison de webhook créé en mode test.

Live Secret Key : la clé secrète du mode réel. Elle commence par sk_live_ (ou rk_live_ pour une clé restreinte).

Live Webhook Secret : le secret de signature (whsec_...) du point de terminaison de webhook créé en mode réel.

Les clés et secrets enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Enregistré — laissez vide pour le conserver. Saisissez une nouvelle valeur uniquement pour la modifier.

Clear saved secrets : cochez une clé ou un secret, puis cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Webhook

Le webhook indique à votre boutique qu'un paiement a été effectué. Dans Stripe Dashboard > Developers > Webhooks, ajoutez un point de terminaison en mode test et un autre en mode réel. Utilisez l'URL affichée dans Endpoint URL dans cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_stripe_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'elle est affichée dans les réglages, car Stripe ne suit pas les redirections.

Sélectionnez ces événements pour chaque point de terminaison (ils sont aussi listés dans cette section) :

Après avoir créé chaque point de terminaison, copiez son secret de signature (whsec_...) depuis Stripe et collez-le dans Test Webhook Secret ou Live Webhook Secret. Les webhooks sans signature valide sont rejetés. Un événement doit être signé avec le secret du mode dans lequel le paiement a été effectué, de sorte qu'un secret de test ne confirme jamais un paiement réel. Sans le webhook, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé.

Commandes

Order Status After Payment : le statut de commande défini après un paiement réussi.

Les paiements différés attendent dans Awaiting Stripe payment. Les écarts de montant ou de devise passent toujours en Stripe payment on hold.

Avancé

Logging : écrit les requêtes Stripe et les webhooks dans logs/strg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés et les données clients ne sont pas journalisées. Default: off. Rien n'est écrit tant qu'il est 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 de la passerelle et le journal. Les transactions et remboursements Stripe ainsi que les statuts de commande du module sont toujours conservés, afin que les commandes existantes continuent de fonctionner. Default: off.

Tunnel de commande

À l'étape de paiement, le client choisit le mode de paiement (par défaut Stripe) et voit la mention Vous serez redirigé vers Stripe pour finaliser le paiement en toute sécurité. Après confirmation, le module crée une session Stripe Checkout pour le total du panier dans la devise du panier et envoie le client sur la page de paiement de Stripe. Il y paie par carte de crédit ou de débit. L'adresse e-mail du client est transmise à Stripe, et le paiement apparaît sur la page Stripe avec la mention Cart # suivie du numéro de panier. À ce stade, aucune commande n'existe encore.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation de Stripe : par le webhook signé ou par une requête serveur vers Stripe lorsque le client revient. La commande est alors créée et le client voit la page standard de confirmation de commande avec Votre paiement avec Stripe a bien été reçu. Pour un paiement différé, la page affiche Votre paiement est en cours de confirmation par Stripe. Vous recevrez un e-mail dès sa confirmation. Si un paiement différé échoue plus tard, la page affiche Votre paiement Stripe n'a pas été finalisé. Veuillez nous contacter au sujet de cette commande. Si Stripe n'a pas encore confirmé le paiement au retour du client, une page Confirmation du paiement affiche le même texte ainsi qu'un bouton Check again ; le webhook crée la commande dès son arrivée.

Si le client annule sur la page Stripe, la session Stripe est fermée et le client revient au tunnel de commande avec Le paiement a été annulé. Vous pouvez réessayer ou choisir un autre mode de paiement. Si le paiement n'a pas été finalisé, le message est Le paiement n'a pas été finalisé. Vous pouvez réessayer ou choisir un autre mode de paiement. Le panier est conservé. Chaque nouvelle tentative ferme la session Stripe précédente, de sorte que le panier ne peut pas être payé deux fois. Si la session précédente s'avère déjà payée, la commande est créée à la place d'un nouveau paiement.

Si Stripe ne peut pas démarrer le paiement, le client reste dans le tunnel de commande avec un message bref, par exemple Le total de la commande est inférieur au montant minimum que Stripe peut prélever dans cette devise. Veuillez choisir un autre mode de paiement. La raison technique est écrite dans le journal.

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

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

Le module n'accepte que les paiements par carte, encaissés immédiatement sur la page Stripe. Il n'a ni cartes enregistrées, ni abonnements ou paiements récurrents, ni formulaire de carte sur le site, ni boutons Apple Pay ou Google Pay sur votre site, ni autorisation et capture séparées.

Commandes et remboursements

Statuts de commande

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

Payment accepted, Delivered or Stripe payment on hold : le paiement a été confirmé. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de paiement Stripe (pi_...) comme identifiant de transaction, et une note indique le paiement Stripe, la session et le mode de confirmation (webhook ou retour).

Awaiting Stripe payment : le client a terminé le tunnel de commande avec un mode de paiement différé. La commande passe au statut payé lorsque Stripe confirme le paiement.

Stripe payment on hold after payment : Stripe a indiqué un montant ou une devise différents du total de la commande (par exemple, le panier a été modifié après le début du paiement), un bon de réduction a été retiré, ou le paiement est arrivé après l'annulation de la commande. La note l'explique. Vérifiez la commande, puis traitez-la ou remboursez le paiement.

Payment error : un paiement différé a échoué.

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

Si un deuxième paiement arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de le vérifier et de rembourser le doublon dans le Stripe Dashboard.

Bloc « Stripe payment »

La page de commande affiche un bloc Stripe payment avec l'identifiant de paiement Stripe (lié au paiement dans le Stripe Dashboard), la session Checkout, le statut du paiement, le montant prélevé par Stripe et le montant remboursé, un badge Test mode pour les paiements de test, l'historique des remboursements et les Stripe notes de la commande.

Remboursements

Dans le bloc Stripe payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Stripe. Confirmez la question Rembourser ce montant via Stripe ? Cette action est irréversible. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes. Les remboursements sont effectués dans le montant et la devise prélevés par Stripe : après un écart de montant ou de devise, vous pouvez donc rembourser jusqu'à ce que le client a réellement payé, et non le total de la commande. Le remboursement est envoyé dans le mode dans lequel le paiement a été effectué (test ou réel), la clé secrète de ce mode doit donc être renseignée. Si Stripe 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 Stripe. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que Stripe a confirmé le paiement.

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

Les remboursements effectués dans le Stripe Dashboard arrivent par le webhook charge.refunded et sont ajoutés aux notes avec le total remboursé dans Stripe. Le statut de la commande et les avoirs ne sont pas modifiés automatiquement. Mettez-les à jour 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 Stripe Gateway est le premier bloc de Modules > Module Manager > VibeFox Stripe 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-stripe 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 : celui 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-le dans votre compte vibefox.net.

Sans clé active, Stripe n'est pas proposé 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 boutique 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 vous ne pouvez pas le tester dans le tunnel de commande. Un rappel apparaît dans Modules > Module Manager, dans 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 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 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 le statut de licence.

Dépannage

Stripe n'apparaît pas dans le tunnel de commande : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel dispose d'une clé secrète : Test Secret Key en mode test, Live Secret Key en mode réel. La page des réglages affiche un avertissement lorsque la clé manque. 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 été effectué, mais aucune commande n'a été créée : le webhook ne fonctionne pas. Dans le Stripe Dashboard, vérifiez que le point de terminaison existe dans le mode utilisé (test ou réel), que son URL est exactement celle affichée dans Endpoint URL et que les quatre événements sont sélectionnés. Vérifiez que le secret de signature de ce point de terminaison se trouve dans le champ correspondant (Test Webhook Secret ou Live Webhook Secret). Le Stripe Dashboard affiche la réponse de votre boutique pour chaque webhook. La commande est aussi créée lorsque le client revient dans la boutique après le paiement.

Le webhook répond Webhook secret not configured : aucun secret de webhook n'est renseigné. Collez le secret de signature dans les réglages.

Le webhook répond Invalid signature : le secret de signature appartient à un autre point de terminaison ou à un autre mode, ou l'horloge du serveur est fausse. Les signatures Stripe sont acceptées dans les 5 minutes suivant l'heure du serveur. La réponse est aussi Invalid signature lorsqu'un événement d'un paiement réel est signé avec le secret de test, ou l'inverse : vérifiez que les secrets de test et réels ne sont pas inversés.

Le webhook répond Busy, retry : la commande é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, parce que le module est désactivé). Stripe relance automatiquement le webhook. Activez Logging pour voir la raison.

L'URL du webhook affiche Method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de Stripe.

Avertissement « The value does not look right » à l'enregistrement : une clé a été collée dans le mauvais champ. Les clés secrètes commencent par sk_test_ / rk_test_ ou sk_live_ / rk_live_, les secrets de webhook par whsec_.

Le client voit une erreur en choisissant Stripe : activez Logging et consultez le champ Log de la page du module. Une clé incorrecte affiche le message indiquant que le mode de paiement n'est pas correctement configuré. Un total de commande inférieur au minimum Stripe pour la devise (par exemple 0.50 EUR) ne peut pas être payé avec Stripe.

Les paiements de test ne confirment pas un paiement réel : les paiements de test et les paiements réels sont séparés. Passez Test Mode sur le mode souhaité et utilisez les clés et le webhook de ce mode.

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

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

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Stripe 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 de la passerelle 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 Stripe ainsi que les statuts de commande Awaiting Stripe payment et Stripe 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.

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