Guide du module Passerelle de paiement Stripe pour Larapen

Acceptez les paiements par carte de crédit et de débit via Stripe. Cet add-on intègre l’API Payment Intents de Stripe à la boutique Larapen, offrant un traitement de carte sécurisé et conforme PCI avec prise en charge de 3D Secure, des mises à jour de commande pilotées par webhooks et des remboursements en un clic.

Cas d’utilisation

Boutique en ligne avec paiements par carte

Vous gérez une boutique sur Larapen vendant des produits physiques ou numériques. Les clients sélectionnent “Carte de crédit” au moment du règlement, saisissent les détails de leur carte dans un formulaire Stripe Elements et paient instantanément.

• Installez l’add-on Stripe en même temps que l’add-on Boutique.
• Saisissez vos clés API Stripe dans Admin → Stripe → Paramètres.
• Stripe apparaît automatiquement comme option de paiement au moment du règlement.
• Les commandes sont confirmées en temps réel via les webhooks.

Téléchargements numériques avec livraison instantanée

Vous vendez des produits numériques (e-books, logiciels, modèles). Stripe confirme le paiement immédiatement, déclenchant la finalisation de la commande et accordant l’accès au téléchargement.

Ventes internationales multi-devises

Configurez la devise en fonction de votre marché cible (USD, EUR, GBP, etc.). Stripe gère la conversion de devises et les réseaux de cartes internationaux.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• L’add-on Boutique (dépendance requise)
• Un compte Stripe avec des clés API (voir Obtenir les clés API)
• Le package Composer stripe/stripe-php

Installation

Étape 1 : Téléverser l’add-on

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Téléverser un add-on. Sélectionnez le fichier ZIP de l’add-on : le système l’extrait automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Repérez Passerelle de paiement Stripe dans la liste et cliquez sur Activer. Ses migrations, ses seeders (le cas échéant) et ses permissions sont mis en place automatiquement.

Étape 3 : Configurer

Naviguez vers Admin → Stripe → Paramètres et saisissez votre clé publique Stripe, votre clé secrète et le secret de signature du webhook. Voir Configuration.

Étape 4 : Configurer les webhooks

Dans le tableau de bord Stripe, créez un endpoint webhook pointant vers https://yoursite.com/stripe/webhook, puis copiez le secret de signature et collez-le dans les paramètres d’administration. Voir Configuration des webhooks.

Code d’achat (clé de licence)

Passerelle de paiement Stripe est vendu comme un produit séparé, il possède donc son propre code d’achat (clé de licence), distinct du code d’achat de l’application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez Passerelle de paiement Stripe dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon dont vous recevez un code d’achat dépend de l’endroit où vous avez acheté le produit.

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande devient Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée : acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour la commande, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour afficher et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d’activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat sur Gumroad produit deux e-mails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d’achat.
• L’e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque → votre achat sur gumroad.com.
• Utilisez la même adresse e-mail sur bedigit.com que sur Gumroad : vos clés sont alors liées automatiquement à votre compte et listées sous Mon compte → Mes licences, même si vous vous inscrivez après l’achat. Vous pouvez aussi ajouter une clé Gumroad manuellement depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d’achat Envato sont délivrés et fournis par Envato Market, jamais envoyés par e-mail par nous, il n’y a donc rien à chercher dans votre dossier de spam : vous récupérez le code depuis votre compte Envato.
• Connectez-vous à votre compte Envato / CodeCanyon, ouvrez la page Downloads, trouvez l’article et choisissez License certificate & purchase code dans le menu déroulant Download. Le code est inscrit dans ce certificat.
• Un code d’achat Envato ressemble à 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 caractères). Il ne change jamais, et le renouvellement du support de l’article n’en délivre pas de nouveau.
• Article officiel Envato : Where Is My Purchase Code?

Configuration

Tous les paramètres sont gérés dans Admin → Stripe → Paramètres (stockés dans la table settings, groupe stripe).

Variables d’environnement

Les variables d’environnement servent de valeurs par défaut. Les paramètres enregistrés dans le panneau d’administration les remplacent.

Obtenir les clés API

1. Connectez-vous au tableau de bord Stripe.
2. Naviguez vers Développeurs → Clés API.
3. Copiez la clé publique (commence par pk_test_ ou pk_live_).
4. Révélez et copiez la clé secrète (commence par sk_test_ ou sk_live_).
5. Collez les deux clés dans Admin → Stripe → Paramètres.

Numéros de cartes de test

Utilisez n’importe quelle date d’expiration future (ex. 12/34) et n’importe quel CVC à 3 chiffres.

Admin : Paramètres

La page des paramètres (Admin → Stripe → Paramètres) est organisée en deux sections :

Clés API

• Clé publique : champ mot de passe masqué avec bascule afficher/masquer. Commence par pk_.
• Clé secrète : champ mot de passe masqué avec bascule afficher/masquer. Commence par sk_. Chiffrée avant le stockage.
• Secret de signature du webhook : champ mot de passe masqué. Commence par whsec_. Utilisé pour vérifier les signatures des webhooks entrants.

Un bandeau d’avertissement rappelle aux administrateurs que les clés sont chiffrées avant le stockage et que les champs doivent être laissés vides pour conserver les valeurs actuelles.

Un encadré d’information fournit des liens directs vers :

• la page des clés API Stripe
• la page des webhooks Stripe
• la documentation des clés Stripe
• les numéros de cartes de test

Options de paiement

• Méthode de capture : Automatique (débiter immédiatement) ou Manuelle (autoriser maintenant, capturer plus tard).
• Devise : code devise à trois lettres en minuscules (ex. usd, eur, gbp).
• 3D Secure : Automatique (uniquement lorsque la banque émettrice l’exige) ou Toujours demander.

Flux de paiement

L’add-on Stripe utilise l’API Payment Intents pour un traitement de carte conforme SCA. Voici le flux de paiement complet :

1. Sélection au règlement : le client sélectionne “Carte de crédit” comme mode de paiement au moment du règlement. Le formulaire de paiement Stripe (Stripe Elements) apparaît.
2. Création de la commande : la boutique crée une commande et appelle StripeGateway::createPaymentIntent($order).
3. Payment Intent : la passerelle crée un PaymentIntent Stripe via l’API, stocke les détails localement dans stripe_payment_intents et retourne le client_secret.
4. Confirmation côté client : le navigateur utilise stripe.confirmCardPayment() avec le client secret et les détails de carte collectés via Stripe Elements.
5. 3D Secure : si la carte nécessite une authentification, Stripe affiche un challenge 3D Secure. Le client le complète dans une fenêtre modale.
6. Confirmation serveur : en cas de succès, le navigateur redirige vers /stripe/confirm?payment_intent={id}. La méthode StripeController::confirm() récupère le PaymentIntent depuis Stripe, met à jour l’enregistrement local et marque la commande comme payée.
7. Webhook de secours : Stripe envoie également un webhook payment_intent.succeeded. Cela garantit que la commande est marquée comme payée même si le client ferme le navigateur avant que la redirection ne se termine.

Confirmation du paiement

Après la confirmation réussie de la carte côté client, le navigateur redirige vers l’endpoint de confirmation côté serveur :

Configuration des webhooks

Les webhooks garantissent que votre site reçoit les mises à jour de statut de paiement même si le client ferme son navigateur.

Créer un endpoint webhook dans Stripe

1. Allez dans Tableau de bord Stripe → Développeurs → Webhooks.
2. Cliquez sur Ajouter un endpoint.
3. Entrez l’URL de votre endpoint : https://yoursite.com/stripe/webhook
4. Sélectionnez les événements suivants :
   • payment_intent.succeeded
   • payment_intent.payment_failed
   • charge.refunded
   • charge.dispute.created
5. Cliquez sur Ajouter un endpoint pour enregistrer.
6. Révélez le secret de signature (commence par whsec_) et collez-le dans Admin → Stripe → Paramètres.

Traitement des remboursements

Les remboursements sont traités via la méthode StripeGateway::refund(), qui peut être appelée depuis l’interface de gestion des commandes de la boutique.

Flux de remboursement

1. L’administrateur initie un remboursement depuis la page de détail de la commande dans le panneau d’administration.
2. Le système appelle StripeGateway::refund($transaction, $amount, $reason).
3. Un Stripe\Refund est créé via l’API en utilisant l’ID du PaymentIntent original.
4. Un nouvel enregistrement Transaction est créé avec le type refund.
5. Le résultat du remboursement est retourné (succès, en attente ou échec).

Remboursements partiels

Le paramètre $amount permet des remboursements partiels. Le montant est spécifié dans la devise de la commande (pas en centimes : la passerelle gère la conversion en centimes en interne).

Statuts de remboursement

Mise à jour

Il existe deux manières de mettre à jour cet add-on : via le panneau d’administration (recommandé) ou en remplaçant manuellement les fichiers.

Méthode 1 : Téléchargement via le panneau d’administration (Recommandé)

1. Téléchargez le dernier fichier .zip de cet add-on.
2. Allez dans Panneau d’administration → Add-ons et cliquez sur le bouton Télécharger.
3. Sélectionnez ou glissez le fichier .zip dans la zone de téléchargement.
4. Une invite de confirmation affichera les numéros de version actuel et nouveau. Cliquez sur Remplacer pour continuer.
5. Allez dans Panneau d’administration → Mise à jour système (/admin/update) pour appliquer les migrations de base de données en attente.

Méthode 2 : Remplacement manuel des fichiers

Étape 1 : Remplacer les fichiers

Remplacez le répertoire de l’add-on par la nouvelle version.

Étape 2 : Mettre à jour le SDK PHP Stripe

Étape 3 : Exécuter les migrations

php artisan migrate

Les migrations en attente ne s’exécutent qu’une seule fois : la commande peut être relancée sans risque.

Étape 4 : Vider les caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

Étape 5 : Vérifier

Visitez Admin → Stripe → Paramètres et confirmez que vos clés API sont toujours configurées. Effectuez un paiement de test pour vérifier l’intégration.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Stripe Payment Gateway et cliquez sur Désactiver.

• Ses routes, ses vues, ses entrées de menu d’administration et ses permissions cessent d’être enregistrées, et ses pages publiques ne répondent plus.
• Ses tables de base de données et toutes les données qu’elles contiennent sont conservées, et ses fichiers restent dans extensions/addons/stripe/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est conservé lui aussi : réactiver l’add-on ne le redemande pas.
• La désactivation est refusée tant qu’un autre add-on actif dépend de celui-ci : désactivez d’abord cet add-on.

Cliquez sur Activer sur la même carte pour le rallumer. Les migrations en attente sont rejouées, les assets republiés, et l’add-on reprend exactement là où il s’était arrêté.

Suppression

La suppression est définitive et détruit les données de l’add-on. Le bouton Supprimer n’apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux temps :

1. Désactivez Stripe Payment Gateway (voir Désinstallation).
2. Cliquez sur Supprimer sur sa carte et confirmez la demande.

Le panneau d’administration, en une seule passe :

• exécute le hook de désinstallation de l’add-on, s’il en fournit un, tant que son code est encore sur le disque ;
• révoque les permissions déclarées dans son addon.json ;
• annule ses migrations, ce qui supprime ses tables de base de données et toutes les lignes qu’elles contiennent, et purge ses entrées de la table migrations, afin qu’une réinstallation ultérieure reparte de zéro ;
• supprime ses assets publiés : public/addons/stripe/, public/vendor/stripe/ et storage/app/public/addons/stripe/ ;
• supprime le dossier de l’add-on extensions/addons/stripe/ ;
• supprime sa ligne dans la table addons (le code d’achat enregistré disparaît avec elle) et vide le cache de l’application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l’add-on est encore actif, lorsqu’un autre add-on actif en dépend, ou lorsque l’utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/stripe/. Dans ce dernier cas, donnez à cet utilisateur le droit d’écriture sur le dossier et sur son parent, puis réessayez.

Supprimer le dossier en FTP ou en SSH n’est pas équivalent : les tables de l’add-on, ses entrées dans la table migrations et sa ligne addons restent en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

Stripe n’apparaît pas comme mode de paiement au règlement

• Assurez-vous que l’add-on Stripe est activé dans Admin → Add-ons.
• Assurez-vous que l’add-on Boutique est également activé (Stripe en dépend).
• Vérifiez que stripe_public_key et stripe_secret_key sont tous deux configurés. La méthode isAvailable() retourne false si l’une des deux est vide.

Le paiement échoue avec “Invalid API Key”

• Vérifiez que la clé secrète commence par sk_test_ (mode test) ou sk_live_ (production).
• Si vous avez récemment renouvelé vos clés dans le tableau de bord Stripe, mettez-les à jour dans les paramètres d’administration.
• Assurez-vous que la clé est correctement chiffrée. Essayez de vider la valeur et de la ressaisir.

Les webhooks retournent des erreurs 400

• Vérifiez que stripe_webhook_secret est défini dans les paramètres d’administration.
• Le secret doit correspondre à l’endpoint spécifique que vous avez créé dans le tableau de bord Stripe (chaque endpoint a son propre secret de signature unique).
• Assurez-vous que l’horloge de votre serveur est synchronisée (Stripe rejette les signatures avec un décalage temporel excessif).
• Vérifiez que l’URL du webhook est https://yoursite.com/stripe/webhook (pas http://).

Le challenge 3D Secure n’apparaît pas

• En mode test, utilisez la carte de test 4000 0025 0000 3155 qui nécessite toujours le 3D Secure.
• En mode automatic, le 3DS ne se déclenche que lorsque la banque émettrice l’exige. Passez en mode any pour le forcer lors des tests.
• Assurez-vous que Stripe.js est correctement chargé. Vérifiez la console du navigateur pour les erreurs JavaScript.

La commande n’est pas marquée comme payée après un paiement réussi

• Vérifiez les logs du serveur pour les erreurs lors de la redirection /stripe/confirm.
• Vérifiez que le webhook est configuré et reçoit les événements. Consultez les logs des webhooks Stripe pour les tentatives de livraison.
• Assurez-vous que la table stripe_payment_intents contient un enregistrement pour l’ID du PaymentIntent. Si ce n’est pas le cas, le paiement n’a pas été initié via le flux standard.
• Vérifiez que l’interface Payable est correctement implémentée sur le modèle Order avec une méthode markAsPaid() fonctionnelle.

Le remboursement échoue avec “No such payment intent”

• Le remboursement utilise le gateway_transaction_id de l’enregistrement Transaction. Assurez-vous qu’il contient l’ID du PaymentIntent Stripe original (commence par pi_).
• Vous ne pouvez pas rembourser un PaymentIntent qui n’a pas encore réussi.

Un client créé à chaque paiement

• La méthode getOrCreateCustomer() vérifie l’existence d’un enregistrement stripe_customers par user_id avant de créer un nouveau client Stripe. Si des doublons apparaissent, vérifiez que la clé étrangère user_id est correctement définie.
• Les paiements en mode invité (sans utilisateur authentifié) ne créent pas d’objets Client Stripe.

Erreurs de non-concordance de devise

• Le paramètre stripe_currency doit correspondre à la devise utilisée par la boutique. Par exemple, si les prix de la boutique sont en EUR, définissez la devise Stripe sur eur.
• Les codes de devise doivent être en minuscules (ex. usd, pas USD).