Guide du module Passerelle de paiement PayPal pour Larapen

Acceptez les paiements avec PayPal sur votre boutique Larapen. Cet add-on intègre l’API REST PayPal pour créer des commandes, capturer les paiements, gérer les webhooks et traiter les remboursements : le tout via l’interface standard de passerelle de paiement de Larapen.

Cas d’utilisation

Boutique en ligne avec paiement PayPal

Vous gérez une boutique e-commerce avec l’add-on Boutique de Larapen et souhaitez proposer PayPal comme moyen de paiement aux côtés d’autres passerelles (par ex. Stripe).

• Installez et activez l’add-on PayPal.
• Saisissez vos identifiants de l’API REST PayPal dans le panneau d’administration.
• Les clients voient PayPal comme moyen de paiement lors de la commande.
• Après sélection, ils sont redirigés vers PayPal pour finaliser le paiement, puis renvoyés vers votre site.

Vente de produits numériques

Vous vendez des téléchargements numériques (e-books, licences logicielles, templates) et souhaitez une confirmation de paiement sécurisée et instantanée.

• Les webhooks PayPal confirment le paiement en temps réel, même si le client ferme son navigateur avant de revenir.
• La boutique marque la commande comme payée et débloque automatiquement les liens de téléchargement numérique.

Boutique multi-devises

Vous vendez à des clients internationaux dans plusieurs devises.

• Configurez la devise PayPal par défaut dans les paramètres d’administration (USD, EUR, GBP, etc.).
• Chaque commande envoie le bon code de devise à PayPal en fonction de la configuration de la boutique.

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 PayPal Business avec des identifiants de l’API REST
• Le package Composer srmklive/paypal (SDK PayPal)

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écharger un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse 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 PayPal 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 → PayPal → Paramètres et saisissez vos identifiants API PayPal. Voir aussi Obtenir les identifiants PayPal. Voir Configuration.

Code d’achat (clé de licence)

Passerelle de paiement PayPal 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 PayPal 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 se gèrent dans Admin → PayPal → Paramètres (stockés dans la table settings, groupe paypal).

Correspondance paramètres en base de données → config

Les paramètres stockés en base de données remplacent les valeurs par défaut du fichier de configuration au démarrage, via le service provider :

Variables d’environnement

Obtenir les identifiants PayPal

1. Allez sur developer.paypal.com/dashboard et connectez-vous avec votre compte PayPal Business.
2. Naviguez vers Apps & Credentials.
3. Cliquez sur Create App (ou sélectionnez une application existante).
4. Copiez le Client ID et le Client Secret depuis la page de détails de l’application.
5. Pour les tests en bac à sable, basculez sur l’onglet Sandbox afin d’obtenir les identifiants du bac à sable.
6. Pour les webhooks, allez dans Webhooks dans le tableau de bord, créez un webhook pointant vers https://yoursite.com/paypal/webhook, et copiez le Webhook ID.

Événements webhook requis

Lors de la création de votre webhook PayPal, abonnez-vous à ces événements :

• PAYMENT.CAPTURE.COMPLETED : le paiement a été capturé avec succès
• PAYMENT.CAPTURE.DENIED : la capture du paiement a été refusée
• PAYMENT.CAPTURE.REFUNDED : un remboursement a été traité

Admin : Paramètres

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

Identifiants API

• Client ID : champ de mot de passe masqué avec bouton afficher/masquer. Votre Client ID de l’API REST PayPal.
• Client Secret : champ de mot de passe masqué avec bouton afficher/masquer. Stocké chiffré dans la base de données.
• ID du Webhook : champ de mot de passe masqué avec bouton afficher/masquer. Utilisé pour vérifier les signatures des webhooks. Optionnel mais recommandé.

Options de paiement

• Mode : menu déroulant permettant de choisir Sandbox (Testing) ou Live (Production). Détermine quel jeu d’identifiants API est utilisé.
• Devise : code de devise ISO 4217 à trois caractères (par ex. USD, EUR, GBP). Utilisé comme devise par défaut pour les commandes PayPal.
• Nom de la marque : le nom affiché sur la page de paiement PayPal (127 caractères max). Le nom de l’application est utilisé si le champ est vide.

Une carte d’aide en haut de la page des paramètres fournit des liens directs vers :

• Tableau de bord développeur PayPal
• Apps & Credentials
• Configuration des webhooks
• Documentation de l’API REST

Flux de paiement

Le flux de paiement PayPal suit le schéma standard de paiement par redirection :

1. Le client choisit PayPal : lors de la commande dans la boutique, le client choisit PayPal comme moyen de paiement.
2. Création de la commande : la boutique appelle PaypalGateway::createPaymentIntent($order), qui crée une commande PayPal via l’API REST avec l’intention CAPTURE.
3. Enregistrement local : un enregistrement est sauvegardé dans la table paypal_orders avec l’ID de la commande PayPal, le montant, la devise, l’URL d’approbation et la référence payable polymorphique.
4. Redirection vers PayPal : le client est redirigé vers la page de paiement hébergée par PayPal (l’approval_url de la réponse de l’API).
5. Le client approuve : le client se connecte à PayPal, vérifie la commande et clique sur “Payer”.
6. Retour sur le site : PayPal redirige le client vers /paypal/return?token={paypal_order_id}.
7. Capture du paiement : la méthode PaypalController::return() appelle PaypalGateway::confirmPayment() pour capturer le paiement autorisé.
8. Finalisation de la commande : si la capture réussit, la commande est marquée comme payée, un enregistrement de transaction est créé et le client est redirigé vers la page de succès.

Annulation

Si le client clique sur “Annuler” sur la page de paiement PayPal, il est redirigé vers /paypal/cancel. Le contrôleur le renvoie vers la page de commande de la boutique avec un message d’avertissement “Paiement annulé”.

Confirmation du paiement

Lorsqu’un paiement est capturé avec succès, la passerelle effectue ces actions :

1. Elle met à jour l’enregistrement paypal_orders avec : status = COMPLETED, capture_id, payer_id, payer_email et confirmed_at.
2. Elle appelle $payable->markAsPaid('paypal', $captureId) sur le modèle de commande.
3. Elle crée un enregistrement Transaction dans la table shop_transactions avec :
   • gateway = 'paypal'
   • gateway_transaction_id = {capture_id}
   • status = 'completed'
   • type = 'payment'
   • des métadonnées incluant paypal_order_id, payer_id et payer_email

Remboursements

La passerelle prend en charge les remboursements complets et partiels via PaypalGateway::refund().

Processus de remboursement

1. L’administrateur lance un remboursement depuis la gestion des commandes de la boutique.
2. La passerelle appelle l’API refundCapturedPayment() de PayPal en utilisant l’ID de capture d’origine.
3. En cas de succès, un nouvel enregistrement Transaction est créé avec type = 'refund'.
4. Le statut de la commande est mis à jour si le remboursement couvre le montant total.

Statuts de remboursement

Configuration du webhook

Les webhooks PayPal fournissent des notifications asynchrones des événements de paiement. Ils servent de filet de sécurité pour confirmer les paiements même lorsque la redirection de retour du client échoue.

URL du webhook

Configurez PayPal pour envoyer les événements webhook à :

Ce point d’entrée est exempt de CSRF et ne nécessite pas d’authentification.

Configuration

1. Allez dans Tableau de bord développeur PayPal → Webhooks.
2. Cliquez sur Add Webhook.
3. Saisissez votre URL de webhook.
4. Sélectionnez les trois événements requis (voir ci-dessous).
5. Copiez le Webhook ID généré et collez-le dans Admin → PayPal → Paramètres.

Mise à jour

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

Méthode 1 : Téléversement 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éverser.
3. Sélectionnez ou faites glisser le fichier .zip dans la zone de téléversement.
4. Une invite de confirmation affichera les numéros de version actuelle et nouvelle. Cliquez sur Remplacer pour continuer.
5. Allez dans Panneau d’administration → Mise à jour du 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 : 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 3 : Vider les caches

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

Étape 4 : Vérifier

Rendez-vous sur PayPal → Paramètres et confirmez que vos identifiants API sont toujours configurés. Essayez un paiement de test en bac à sable pour vous assurer que tout fonctionne correctement.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez PayPal 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/paypal/. 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 PayPal 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/paypal/, public/vendor/paypal/ et storage/app/public/addons/paypal/ ;
• supprime le dossier de l’add-on extensions/addons/paypal/ ;
• 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/paypal/. 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

“Les identifiants API PayPal ne sont pas configurés”

• Assurez-vous d’avoir saisi à la fois le Client ID et le Client Secret dans Admin → PayPal → Paramètres.
• Vérifiez que le bon Mode est sélectionné : les identifiants du bac à sable ne fonctionnent pas en mode live et inversement.
• Vérifiez que les identifiants correspondent au bon mode (bac à sable ou live).

“L’authentification PayPal a échoué”

• Vérifiez soigneusement que le Client ID et le Client Secret sont corrects (pas d’espaces ni de sauts de ligne supplémentaires).
• Assurez-vous que votre application PayPal n’est pas suspendue ou supprimée.
• Vérifiez que votre serveur peut atteindre api-m.sandbox.paypal.com (bac à sable) ou api-m.paypal.com (live) en HTTPS.
• Consultez les journaux du serveur pour obtenir les messages d’erreur détaillés de l’API PayPal.

Le client est redirigé vers le paiement mais celui-ci n’est pas capturé

• L’URL de retour n’a peut-être pas été atteinte (le client a fermé son navigateur). Vérifiez si le webhook a reçu un événement PAYMENT.CAPTURE.COMPLETED.
• Assurez-vous que l’URL du webhook est correctement configurée dans le tableau de bord développeur PayPal.
• Vérifiez que l’enregistrement paypal_orders a bien été créé (consultez la colonne status).

Les webhooks ne sont pas reçus

• Vérifiez que l’URL du webhook est accessible publiquement en HTTPS.
• Consultez le tableau de bord développeur PayPal → Webhooks → Events pour connaître le statut de livraison.
• Assurez-vous que le webhook n’est pas derrière des règles de pare-feu basées sur l’IP qui bloquent les serveurs de PayPal.
• Pour le développement local, utilisez un service de tunnel (par ex. ngrok) pour exposer votre serveur local.

La vérification de la signature du webhook échoue

• Assurez-vous que l’ID du Webhook dans les paramètres d’administration correspond à celui du tableau de bord développeur PayPal.
• Si vous avez récemment recréé le webhook, mettez à jour l’ID du Webhook dans vos paramètres.
• Laissez l’ID du Webhook vide pour désactiver la vérification de signature (non recommandé en production).

Le remboursement échoue : “Refund failed”

• Assurez-vous que le paiement d’origine a bien été capturé (statut COMPLETED).
• Vérifiez que le montant du remboursement ne dépasse pas le montant du paiement d’origine.
• PayPal peut refuser les remboursements pour les paiements de plus de 180 jours.
• Consultez les journaux du serveur pour connaître le message d’erreur précis de l’API PayPal.

Commandes bloquées au statut CREATED ou APPROVED

• Le client a peut-être approuvé le paiement mais la capture a échoué. Consultez les journaux du serveur pour repérer les erreurs survenues pendant confirmPayment().
• Essayez de traiter la capture manuellement depuis le tableau de bord marchand PayPal.
• Assurez-vous que le package srmklive/paypal est à jour.

Erreurs “Array to string conversion”

• Cela se produit généralement lorsque la bibliothèque srmklive/paypal reçoit des clés de configuration inattendues. La passerelle filtre la configuration pour ne transmettre que les clés prises en charge. Assurez-vous d’utiliser une version compatible du package.
• Videz le cache de configuration : php artisan config:clear