Stripe pour PrestaShop : guide complet d’intégration des paiements

Les exigences du module Stripe (API Payment Intents, événements de webhook, synchronisation des états de commande), les numéros de cartes de test, le comportement SCA/3DS2 et l’étape de vérification de domaine Apple Pay décrits ici sont à jour pour PrestaShop 1.6, 1.7, 8.x et 9.x. Les cartes de test et les noms d’événements Stripe proviennent de sa documentation actuelle ; vérifiez tout ce qui concerne les tarifs dans votre propre tableau de bord Stripe.

La plupart des guides Stripe pour PrestaShop s’arrêtent à « collez vos clés API et c’est terminé ». C’est justement la partie qui ne casse presque jamais. Ce qui casse, discrètement, quelques jours après la mise en ligne, quand vous avez cessé de surveiller, c’est le webhook qui ne s’est jamais déclenché, la commande bloquée dans les limbes alors que l’argent a déjà été encaissé, ou le défi 3D Secure qui renvoie un client prêt à payer vers son panier. Faire fonctionner Stripe sur PrestaShop prend dix minutes. Le faire réconcilier chaque paiement, remboursement et litige dans votre liste de commandes, dans la bonne devise, tout en survivant à la prochaine mise à jour du cœur, c’est cette intégration-là que ce guide traite vraiment.

Voici le déroulé de mise en œuvre : choisir un module adapté à l’architecture de PrestaShop, configurer correctement les clés et les webhooks, respecter les règles européennes de SCA, activer Apple Pay et Google Pay, et comprendre les modes de défaillance propres à PrestaShop qui laissent des commandes coincées. Si vous hésitez encore à savoir si Stripe est le bon prestataire de paiement pour vous, c’est une autre question, nous le comparons directement à PayPal dans Stripe vs PayPal, et nous le confrontons à l’ensemble du marché dans les meilleurs modules de paiement pour PrestaShop. Ici, nous partons du principe que la décision est prise : vous voulez Stripe, et vous voulez l’intégrer correctement.

Choisir un module Stripe adapté à PrestaShop

Stripe, en soi, n’est qu’une API. Ce qui le transforme en bouton de paiement opérationnel, synchronise les statuts de commande et stocke les données client dans les tables de PrestaShop, c’est le module, et ce choix compte plus que tout ce que vous ferez dans le tableau de bord Stripe. Deux exigences techniques déterminent si un module mérite seulement d’être installé :

• Il doit utiliser l’API Payment Intents, pas l’ancienne API Charges. Payment Intents est l’architecture actuellement requise par Stripe pour les modules compatibles SCA, et c’est elle qui permet à l’authentification forte du client de fonctionner automatiquement. Les modules basés sur l’ancien flux Charges (ou Sources) sont obsolètes et mal adaptés à la SCA, évitez-les. Si la description d’un module parle encore de « Charges » ou de « tokens » sans mentionner Payment Intents, passez votre chemin.
• Il doit réconcilier les paiements avec les états de commande PrestaShop. Un paiement réussi dans Stripe ne représente que la moitié du travail. Le module doit associer cette réussite à un état de commande PrestaShop (Paiement accepté), gérer les remboursements émis depuis votre back-office et enregistrer l’identifiant de transaction Stripe dans la commande. Les modules qui ignorent cette étape vous obligent à croiser manuellement deux systèmes chaque fois qu’un client pose une question sur un débit.

Le module Stripe officiel gratuit couvre les bases pour un catalogue simple. Les modules premium ajoutent les cartes enregistrées, les boutons de portefeuille express, la validation des bons de réduction en temps réel et une vue des litiges/remboursements directement dans PrestaShop. Nous avons déjà détaillé tout le paysage, gratuit contre premium, ce que chaque niveau apporte réellement, dans le comparatif des modules de paiement, donc nous ne le reprendrons pas ici. Le point clé pour ce guide : vérifiez Payment Intents et la synchronisation des états de commande avant d’installer quoi que ce soit, car les ajouter après coup est pénible.

Étape 1, Créer et vérifier votre compte Stripe

Inscrivez-vous sur stripe.com et terminez la vérification de votre entreprise avant de toucher à PrestaShop, Stripe examine votre site en ligne et l’approbation du compte peut prendre un jour ou deux, alors lancez-la tôt. Vous aurez besoin de documents d’immatriculation de l’entreprise (ou d’une pièce d’identité pour les entrepreneurs individuels), de coordonnées bancaires pour les virements et de l’URL de votre boutique en production.

Une fois connecté, allez dans Developers → API keys. Vous verrez deux jeux de clés : test mode et live mode. Effectuez toute votre configuration en mode test d’abord, les clés de test traitent de faux paiements sans déplacer d’argent réel, et vous ne voulez pas découvrir un webhook cassé avec la carte d’un vrai client.

Étape 2, Installer le module et saisir vos clés

Téléversez le module depuis Modules → Module Manager → Upload a module, puis ouvrez sa configuration. Les modules Stripe utilisent différentes méthodes de connexion. Si le vôtre exige la saisie manuelle de ces trois identifiants, consultez ses instructions et comprenez le rôle de chacun pour repérer une valeur incorrecte :

• Clé publique (pk_test_… / pk_live_…) : utilisée dans le navigateur pour afficher le champ de carte. Elle est conçue pour être publique, son exposition ne constitue pas un problème de sécurité.
• Clé secrète (sk_test_… / sk_live_…) : authentifie les appels serveur vers Stripe. Elle ne doit jamais apparaître dans du code côté client ou dans les fichiers du thème. Le module la stocke côté serveur ; si vous voyez un jour une clé sk_ dans le code source d’une page, arrêtez tout et remplacez-la immédiatement dans le tableau de bord Stripe.
• Secret de signature du webhook (whsec_…) : configuré à l’étape suivante. Le module l’utilise pour prouver que les appels de webhook entrants proviennent bien de Stripe et n’ont pas été falsifiés.

L’erreur la plus fréquente ici consiste à mélanger clés de test et clés de production, une clé publique pk_live_ associée à une clé secrète sk_test_ produit des erreurs déroutantes du type « no such payment intent ». Gardez les deux clés dans le même mode.

Étape 3, Configurer les webhooks (c’est là que les intégrations PrestaShop échouent)

Les webhooks permettent à Stripe d’informer votre boutique de tout ce qui se produit en dehors de la fenêtre de paiement en direct : un paiement différé finalement validé, l’ouverture d’un litige, un remboursement traité côté Stripe, le renouvellement d’un abonnement. Sans webhook fonctionnel, votre boutique ne l’apprend tout simplement jamais, d’où le symptôme classique d’une intégration Stripe cassée : « l’argent est dans Stripe mais la commande PrestaShop est toujours en attente ».

Dans le tableau de bord Stripe, allez dans Developers → Webhooks → Add endpoint. Renseignez le contrôleur de webhook de votre module, pour notre module Stripe Express Checkout, l’URL suit le modèle de front-controller de PrestaShop, et vous la trouverez affichée dans la page de configuration du module afin de pouvoir la copier exactement au lieu de la deviner. Abonnez-vous au minimum à ces événements :

• payment_intent.succeeded. Confirme qu’un paiement est terminé ; fait passer la commande à Paiement accepté.
• payment_intent.payment_failed. Permet à la boutique de réagir aux refus au lieu de laisser une commande fantôme.
• charge.dispute.created. Signale une rétrofacturation dès son ouverture, tant qu’il est encore temps de répondre.
• charge.refunded, maintient un remboursement émis côté Stripe synchronisé avec la commande PrestaShop.
• checkout.session.completed, nécessaire si vous utilisez le Checkout hébergé de Stripe plutôt qu’un formulaire intégré.

Copiez le secret de signature de l’endpoint (whsec_…) dans la configuration du module. Un module bien conçu vérifie cette signature à chaque appel (le nôtre rejette toute requête dont la signature ne se valide pas avec un HTTP 400 avant même de toucher à votre base de données), de sorte qu’un faux « paiement réussi » ne puisse pas créer une commande gratuite. Après l’enregistrement, envoyez un événement de test depuis le tableau de bord Stripe et vérifiez que le module l’a journalisé. Si le webhook n’arrive jamais, les coupables habituels sont un pare-feu ou un CDN (Cloudflare en particulier) qui bloque la requête, une règle .htaccess qui masque l’URL du front-controller, ou un secret de signature périmé, consultez Developers → Webhooks pour voir les tentatives de livraison échouées ainsi que le journal d’erreurs PHP de votre serveur.

[SCREENSHOT: l’écran Add endpoint du tableau de bord Stripe avec l’URL du webhook PrestaShop saisie et les cinq événements payment_intent / charge / checkout sélectionnés dans le sélecteur d’événements]

Étape 4, Tester chaque scénario avant la mise en production

Stripe fournit des numéros de cartes de test qui forcent chaque résultat, afin que vous puissiez vérifier tout le flux sans argent réel :

Exécutez chaque scénario et observez ce que fait PrestaShop, pas seulement ce que Stripe rapporte. L’état de la commande, l’e-mail de confirmation, l’ajustement du stock et l’enregistrement de la transaction dans le back-office doivent tous arriver correctement. C’est l’étape que beaucoup sautent, et c’est précisément celle qui détecte le problème de webhook ci-dessus avant qu’un client ne le subisse.

SCA et 3D Secure 2 : pris en charge, si vous avez choisi le bon module

L’authentification forte du client est entrée en vigueur dans l’Espace économique européen le 14 septembre 2019, même si les régulateurs ont accordé une période de migration qui a repoussé l’application effective jusqu’à la fin de 2020 (et jusqu’en mars 2021 au Royaume-Uni). Elle est désormais pleinement applicable, ce qui signifie concrètement que de nombreux paiements par carte européens peuvent exiger une authentification à deux facteurs 3D Secure 2, tandis que Stripe et l’émetteur décident quand des exemptions ou des parcours sans friction s’appliquent. Le point rassurant : si votre module utilise l’API Payment Intents (l’exigence par laquelle nous avons commencé), Stripe décide quand un défi est nécessaire et exécute lui-même le flux d’authentification. Le rôle de votre boutique consiste simplement à gérer la réponse, c’est pourquoi la carte de test 4000 0000 0000 3220 ci-dessus est si importante.

Trois comportements méritent d’être connus pour éviter les surprises :

• Exemptions de faible valeur. Les petites transactions peuvent être éligibles à une exemption du défi ; Stripe la demande automatiquement, mais la banque du client a le dernier mot, donc vous ne pouvez pas compter dessus.
• Paiements récurrents et cartes enregistrées. Le premier paiement est authentifié de manière interactive ; les débits ultérieurs initiés par le marchand sur une carte enregistrée ne redemandent pas d’authentification, un point important si vous vendez des abonnements.
• Abandon au moment du défi. Une partie des clients quitte le parcours quand la fenêtre 3DS2 apparaît. Vous ne pouvez pas l’éliminer, mais une interface d’authentification rapide et native en réduit l’impact, une raison de plus pour laquelle la qualité front-end du module compte.

Activer Apple Pay et Google Pay

Apple Pay et Google Pay ne sont pas des intégrations Stripe séparées, ils reposent sur les boutons Payment Request / Express Checkout de Stripe. Activez-les et les acheteurs éligibles voient un bouton de portefeuille natif qui finalise la commande avec une empreinte digitale ou une reconnaissance faciale au lieu de saisir une carte. Pour les clients mobiles en particulier, cela supprime la partie la plus pénible du paiement. (Notre module Stripe Express Checkout est précisément conçu autour de cela : il peut placer le bouton de portefeuille sur les pages produit, panier et paiement, afin qu’un client récurrent paie en quelques secondes sans jamais entrer dans le parcours traditionnel.)

Apple Pay exige une étape supplémentaire que Google Pay n’impose pas, la vérification du domaine :

• Enregistrez votre domaine dans Settings → Payments → Payment methods → Apple Pay dans le tableau de bord Stripe.
• Téléversez le fichier de vérification Stripe vers yourstore.com/.well-known/apple-developer-merchantid-domain-association (les modules bien conçus s’en chargent pour vous ; confirmez que le fichier est accessible en HTTPS).
• Activez le bouton Payment Request / portefeuille dans les paramètres du module.

Google Pay ne nécessite aucun fichier. Il s’active dès que le bouton de portefeuille est activé. Les boutons de portefeuille font partie des gains de conversion mobile les plus évidents disponibles pour une boutique PrestaShop, même si l’ampleur du gain dépend entièrement de la part de trafic mobile et de la lourdeur de votre paiement actuel, mesurez-le sur votre propre boutique plutôt que de vous fier à un pourcentage accrocheur.

Litiges et rétrofacturations

Accepter les cartes signifie accepter le litige occasionnel ; l’objectif est de faire d’une réponse à un litige une tâche de cinq minutes, pas une chasse aux informations entre deux systèmes. Trois habitudes font l’essentiel du travail :

• Répondez dans la fenêtre de dépôt de preuves de Stripe. Vous disposez d’un nombre fixe de jours pour soumettre les preuves, confirmation de commande, suivi d’expédition, confirmation de livraison, toute correspondance avec le client. Manquez ce délai et le litige est perdu par défaut.
• Utilisez Stripe Radar. Radar attribue un score de fraude à chaque transaction et peut bloquer ou mettre en attente les plus risquées avant qu’elles ne deviennent des litiges ; la version de base est incluse, et vous pouvez ajouter des règles personnalisées au niveau supérieur.
• Gardez les preuves là où vous pouvez les retrouver. Un module qui enregistre la transaction Stripe dans la commande PrestaShop, et expose les remboursements et l’état des litiges dans le back-office, vous évite de vous connecter à Stripe et de croiser des numéros de commande sous pression. (C’est l’une des choses que notre module Express Checkout remonte dans l’administration native de PrestaShop : les débits, remboursements et données de paiement sont attachés à la commande, de sorte que les preuves sont déjà rassemblées.)

Garder le paiement Stripe rapide

Une intégration Stripe négligée peut ajouter plusieurs secondes à votre paiement, qui est le dernier endroit où vous pouvez vous permettre d’être lent. Trois règles permettent de garder un parcours réactif :

• Chargez Stripe.js de façon asynchrone afin qu’il ne bloque jamais le rendu de la page.
• Initialisez le formulaire de paiement seulement lorsqu’il est nécessaire, à l’étape de paiement, pas sur le panier ni sur chaque page produit.
• Utilisez le Payment Element de Stripe, son composant unifié actuel, plutôt que l’ancien Card Element. Une seule intégration peut alors afficher les moyens de paiement pertinents selon le pays de l’acheteur, cartes, portefeuilles et moyens locaux, sans chemins de code séparés.

C’est sur ce dernier point que Stripe mérite discrètement sa place pour les boutiques transfrontalières : le même Payment Element peut présenter les moyens de paiement locaux que les acheteurs européens connaissent et auxquels ils font confiance. Si vos clients se trouvent sur des marchés aux habitudes locales fortes, cela vaut la peine d’en tirer parti, voyez à quoi ressemblent ces attentes dans les moyens de paiement pour l’e-commerce européen, l’impact conversionnel de leur disponibilité dans BLIK, iDEAL et Bancontact, et l’angle du paiement différé (Klarna et autres, que Stripe peut aussi afficher) dans acheter maintenant, payer plus tard. Pour les boutiques polonaises en particulier, si vous avez besoin d’une prise en charge P24 pleinement native ou de fonctionnalités propres au marché polonais, il vaut la peine de comparer le support Przelewy24 de Stripe avec un module Przelewy24 dédié, comme nous le détaillons dans Przelewy24 pour PrestaShop.

Là où le Payment Element rencontre la mise en page de votre paiement

Configurer Stripe correctement permet au paiement d’être validé ; l’apparence de l’étape de paiement détermine combien de clients l’atteignent. Si vous voulez que le champ de carte Stripe, le bouton de portefeuille Apple Pay / Google Pay et les éventuels moyens de paiement locaux apparaissent dans une étape de paiement unique, propre et sur une seule page, plutôt qu’éparpillés dans un paiement par défaut en plusieurs étapes, c’est une décision de couche de paiement qui accompagne le câblage Stripe, sans se trouver à l’intérieur. Notre module Checkout Revolution est conçu exactement pour cette présentation en une seule étape, et notre module Stripe Express Checkout gère la partie Stripe sous-jacente. Ensemble, ils offrent au client une étape de paiement simplifiée, avec le bouton de portefeuille en haut et les cartes en dessous, tandis que tout ce que vous avez configuré dans ce guide, webhooks, synchronisation des états de commande, SCA, continue à se réconcilier proprement en arrière-plan.

Dépanner les échecs propres à PrestaShop

Argent dans Stripe, commande toujours en attente

C’est presque toujours un problème de webhook : l’endpoint est inaccessible, bloqué ou signé avec le mauvais secret. Consultez Developers → Webhooks pour repérer les livraisons échouées, vérifiez que le secret de signature du module correspond à l’endpoint et assurez-vous qu’aucun CDN ni pare-feu n’intercepte l’appel. C’est le ticket de support Stripe numéro un sur PrestaShop, et c’est la raison d’être de l’étape 3.

Commandes en double

Deux chemins créent la même commande, le webhook et la redirection de retour du client après paiement, ou le client double-clique sur payer. Un module correctement construit utilise des clés d’idempotence et vérifie l’existence d’une commande associée à l’intention de paiement avant d’en créer une nouvelle. Si vous voyez des doublons, le module ne déduplique pas, et c’est un problème de module, pas de configuration.

Incohérences de devise

Stripe débite dans la devise que vous lui indiquez. Si PrestaShop affiche un prix en EUR mais que le module crée l’intention de paiement en USD, le client est facturé d’un montant différent de celui qu’il a vu. Le module doit lire la devise active du panier et transmettre exactement ce code ISO à Stripe, vérifiez ce point si vous exploitez une boutique multidevise.

La checklist de mise en production

Avant de remplacer les clés de test par les clés de production, vérifiez chaque ligne :

• Les quatre scénarios de cartes de test passent, réussite, refus, défi 3DS2, carte expirée.
• Les webhooks sont configurés et vous avez vu un événement de test arriver puis être traité.
• La correspondance des états de commande est correcte (payment_intent.succeeded → Paiement accepté).
• Les e-mails de confirmation partent après un paiement réussi.
• Un remboursement émis depuis le back-office PrestaShop atteint Stripe et met à jour la commande.
• La vérification de domaine Apple Pay est terminée et le bouton de portefeuille s’affiche sur mobile.
• Stripe Radar dispose au moins d’une règle de base (par exemple bloquer les pays vers lesquels vous n’expédiez pas).
• Tout le flux fonctionne sur un vrai téléphone, pas seulement dans un navigateur de bureau.

Stripe est un excellent choix par défaut pour PrestaShop, car les parties difficiles, SCA, portefeuilles, dizaines de moyens de paiement depuis une seule intégration, sont prises en charge par la plateforme une fois le câblage correct. Ce câblage constitue le vrai travail, et il concerne presque entièrement les webhooks et la synchronisation des états de commande, là où un module natif PrestaShop justifie son coût : notre module Stripe Express Checkout mypresta.rocks vérifie les signatures de webhook, synchronise les débits et remboursements directement sur vos commandes, et place le bouton Apple Pay / Google Pay sur les pages où les clients sont prêts à acheter, afin que l’intégration que vous mettez en place aujourd’hui continue à se réconcilier proprement longtemps après que vous avez cessé de la surveiller. Et comme proposer les moyens de paiement que vos clients utilisent réellement est aussi un levier de conversion, il vaut la peine de garder en tête pourquoi plus d’options de paiement signifie plus de ventes au moment de décider lesquelles activer.

Questions fréquentes

Le paiement apparaît comme réussi dans Stripe, mais la commande PrestaShop est toujours en attente. Qu’est-ce qui ne va pas ?

Le webhook n’atteint pas votre boutique. Stripe confirme tout ce qui se produit en dehors de la fenêtre de paiement en direct (validation différée, remboursement, litige) en appelant l’endpoint de webhook de votre module, si cet endpoint est inaccessible, bloqué par Cloudflare ou un pare-feu, masqué par une règle .htaccess, ou signé avec un secret whsec_ périmé, PrestaShop n’apprend jamais que le paiement est validé. Ouvrez Developers → Webhooks dans Stripe et recherchez les tentatives de livraison échouées, confirmez que le secret de signature du module correspond à l’endpoint, puis vérifiez votre journal d’erreurs PHP. C’est le ticket de support Stripe numéro un sur PrestaShop.

À quels événements Stripe le module PrestaShop doit-il s’abonner ?

Au minimum : payment_intent.succeeded (fait passer la commande à Paiement accepté), payment_intent.payment_failed (gère les refus), charge.dispute.created (fait remonter les rétrofacturations tôt) et charge.refunded (garde les remboursements côté Stripe synchronisés). Ajoutez checkout.session.completed si vous utilisez le Checkout hébergé de Stripe plutôt qu’un formulaire intégré. Abonnez-vous à ces événements, copiez le secret de signature whsec_ de l’endpoint dans le module, puis envoyez un événement de test depuis le tableau de bord pour confirmer qu’il est traité.

Dois-je faire quelque chose de spécial pour SCA / 3D Secure 2 ?

Non, si votre module utilise l’API Payment Intents. Stripe décide quand un défi 3D Secure 2 est requis et exécute lui-même le flux d’authentification, votre boutique se contente de gérer la réponse. C’est pourquoi l’exigence Payment Intents est la première chose à vérifier avant d’installer un module ; un module encore basé sur l’ancienne API Charges peut mal gérer la SCA européenne. Testez avec la carte 4000 0000 0000 3220, qui force un défi 3DS2, et vérifiez que le client revient sur la commande plutôt que sur le panier après l’authentification.

Pourquoi certains clients obtiennent-ils des erreurs « no such payment intent » ?

Presque toujours à cause d’un mélange de clés de test et de production. Une clé publique pk_live_ associée à une clé secrète sk_test_ (ou l’inverse) pousse Stripe à chercher une intention de paiement dans le mauvais environnement, ce qui produit cette erreur. Les deux clés doivent être dans le même mode. Revérifiez les clés publique et secrète dans la configuration du module et assurez-vous qu’elles sont toutes deux en test ou toutes deux en production, conformément au mode que vous voulez utiliser.

Faut-il une configuration séparée pour Apple Pay et Google Pay ?

Ils reposent tous deux sur le bouton Payment Request / Express Checkout de Stripe ; l’activation de ce bouton active donc les deux. La seule étape supplémentaire concerne Apple Pay : la vérification du domaine. Enregistrez votre domaine dans Settings → Payments → Payment methods → Apple Pay dans Stripe et assurez-vous que le fichier de vérification à l’adresse yourstore.com/.well-known/apple-developer-merchantid-domain-association est accessible en HTTPS (les bons modules le placent pour vous). Google Pay ne nécessite aucun fichier. Il s’active dès que le bouton de portefeuille est activé.