Passerelle de paiement Stripe

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 avec la boutique Larapen, offrant un traitement de carte sécurisé et conforme PCI avec support 3D Secure, mises à jour des commandes par webhooks et remboursements en un clic.

Cas d'utilisation

Boutique en ligne avec paiements par carte

Vous gérez une boutique en ligne sur Larapen vendant des produits physiques ou numériques. Les clients sélectionnent « Carte bancaire » au moment du paiement, 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 Shop.
• Entrez 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 Shop (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 : Placer l'add-on

Copiez ou créez un lien symbolique du dossier stripe dans le répertoire "extensions/addons" de votre Larapen :

Étape 2 : Installer le SDK PHP Stripe

Étape 3 : Activer l'add-on

Allez dans Admin → Add-ons → Add-ons installés et activez Passerelle de paiement Stripe.

Étape 4 : Exécuter les migrations

Cela crée 2 tables : stripe_customers et stripe_payment_intents.

Étape 5 : Configurer les clés API

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

Étape 6 : Configurer les webhooks

Dans le Tableau de bord Stripe, créez un endpoint webhook pointant vers :

Sélectionnez les événements listés dans Événements gérés. Copiez le secret de signature et collez-le dans les paramètres d'administration. Voir Configuration des webhooks.

Configuration

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

Paramètre	Description	Défaut
stripe_public_key	Clé publiable Stripe (commence par pk_). Chiffrée au repos.	(vide)
stripe_secret_key	Clé secrète Stripe (commence par sk_). Chiffrée au repos.	(vide)
stripe_webhook_secret	Secret de signature du webhook (commence par whsec_). Chiffré au repos.	(vide)
stripe_capture_method	Mode de capture des paiements : automatic (immédiat) ou manual (autoriser puis capturer plus tard).	automatic
stripe_currency	Code devise ISO à trois lettres en minuscules (ex. usd, eur, gbp).	usd
stripe_request_three_d_secure	Quand demander le 3D Secure : automatic (uniquement lorsque requis par la banque émettrice) ou any (toujours demander).	automatic

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é publiable (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

Numéro de carte	Scénario
4242 4242 4242 4242	Paiement réussi
4000 0025 0000 3155	Nécessite une authentification 3D Secure
4000 0000 0000 9995	Refusé (fonds insuffisants)

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é publiable : 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 :

• Page des clés API Stripe
• Page des webhooks Stripe
• Documentation des clés Stripe
• 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 requis par la banque émettrice) 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 bancaire » 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 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://votresite.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 l'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

Statut	Description
succeeded	Remboursement traité immédiatement. Statut de la transaction : completed.
pending	Remboursement en cours de traitement (peut prendre 5–10 jours ouvrables pour certains modes de paiement). Statut de la transaction : pending.
failed	Le remboursement n'a pas pu être traité. Détails de l'erreur enregistrés dans les logs.

Mise à jour

É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

Étape 4 : Vider les caches

É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é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 Shop est également activé (Stripe en dépend).
• Vérifiez que stripe_public_key et stripe_secret_key sont configurées. 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://votresite.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).