Guide du module Passerelle de paiement Paddle pour Larapen

Acceptez les paiements via Paddle : une plateforme merchant of record qui gère les paiements, les taxes et la conformité. S’intègre à l’add-on Boutique de Larapen via le contrat PaymentGatewayInterface.

Cas d’utilisation

Vente de produits numériques

Vous vendez des produits numériques (thèmes, plugins, e-books) via la Boutique Larapen et souhaitez que Paddle gère la conformité fiscale mondiale et les versements.

• Installez l’add-on Paddle en même temps que l’add-on Boutique.
• Configurez vos identifiants API Paddle dans le panneau d’administration.
• Les clients sélectionnent Paddle au moment du paiement et paient via l’overlay.
• Paddle collecte les taxes, traite le paiement et vous envoie le revenu net.

Boutique de produits physiques ou mixtes

Vous vendez des produits physiques ou un mélange de produits physiques et numériques et souhaitez une passerelle de paiement fiable.

• Paddle prend en charge les cartes de crédit/débit, PayPal, Apple Pay, Google Pay et les méthodes de paiement locales.
• Les commandes sont confirmées via des webhooks, garantissant qu’aucun paiement n’est perdu même si le client ferme son navigateur.

Tests en sandbox

Utilisez l’environnement sandbox de Paddle pour le développement et les tests avant de passer en production.

• Définissez l’environnement sur “Sandbox” dans les paramètres d’administration.
• Utilisez les numéros de carte de test de Paddle pour simuler des paiements.
• Passez en “Production” lorsque vous êtes prêt pour les paiements réels.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• L’add-on Boutique doit être installé et actif (dépendance déclarée)
• Un compte Paddle : paddle.com
• Le SDK PHP Paddle (paddle/paddle-php-sdk) installé via Composer

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 Paddle 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 → Paddle → Paramètres et saisissez votre clé API, votre jeton côté client, votre ID vendeur et le secret du webhook. Voir aussi Obtenir les identifiants Paddle. Voir Configuration.

Étape 4 : Configurer les webhooks

1. Ouvrez votre tableau de bord Paddle → Developer Tools → Notifications.
2. Créez une nouvelle destination de notification pointant vers https://yoursite.com/paddle/webhook.
3. Sélectionnez ces événements : transaction.completed, transaction.payment_failed, transaction.updated, adjustment.created, adjustment.updated.
4. Copiez le secret du webhook et collez-le dans les paramètres d’administration.

Code d’achat (clé de licence)

Passerelle de paiement Paddle 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 Paddle 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 → Paddle → Paramètres (stockés dans la table settings, groupe paddle).

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 identifiants Paddle

Clé API & jeton côté client

1. Connectez-vous à votre tableau de bord Paddle (ou au tableau de bord sandbox pour les tests).
2. Naviguez vers Outils développeur → Authentification.
3. Copiez votre clé API (utilisée pour les appels API côté serveur).
4. Copiez votre jeton côté client (utilisé pour l’initialisation de Paddle.js).

ID vendeur

1. Dans le tableau de bord Paddle, votre ID vendeur est affiché dans les paramètres du compte ou dans l’URL.
2. Copiez l’ID numérique et saisissez-le dans les paramètres d’administration.

Secret du webhook

1. Allez dans Outils développeur → Notifications dans le tableau de bord Paddle.
2. Créez une nouvelle destination de notification avec l’URL https://yoursite.com/paddle/webhook.
3. Sélectionnez les événements auxquels vous abonner (voir Événements supportés).
4. Copiez le secret du webhook généré et saisissez-le dans les paramètres d’administration.

Admin : Paramètres

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

Identifiants API

Trois champs de mot de passe masqués avec des boutons afficher/masquer :

• Clé API : votre clé API Paddle depuis Outils développeur > Authentification. Utilisée pour tous les appels API côté serveur (création de transactions, traitement des remboursements).
• Jeton côté client : votre jeton côté client Paddle. Utilisé pour initialiser Paddle.js sur la page de paiement. Les jetons sandbox commencent par test_.
• Secret du webhook : utilisé pour vérifier la signature HMAC-SHA256 des requêtes de webhook entrantes.

La page affiche également un panneau d’information avec des liens directs vers :

• le tableau de bord Paddle (production et sandbox)
• Outils développeur > Authentification (clés API)
• Outils développeur > Notifications (webhooks)
• la documentation de l’API Paddle
• les numéros de carte de test pour les tests en sandbox

Options de paiement

• Environnement : menu déroulant pour sélectionner sandbox (test) ou production (réel).
• ID vendeur : champ texte pour votre ID vendeur Paddle. Requis pour l’initialisation de Paddle.js.
• Devise : code devise à 3 caractères (ex. : USD, EUR, GBP). Doit correspondre à la devise de votre boutique.

Flux de paiement

L’add-on Paddle utilise un flux de paiement par overlay propulsé par Paddle.js v2. Voici le cycle de vie complet du paiement :

1. Le client sélectionne Paddle : sur la page de paiement de la boutique, le client sélectionne “Paddle” comme méthode de paiement. Un message d’information apparaît : “Vous serez redirigé vers le paiement sécurisé de Paddle.”
2. Soumission du formulaire (AJAX) : lorsque le client soumet le formulaire de paiement, JavaScript intercepte la soumission et l’envoie via fetch() avec des en-têtes JSON.
3. Le serveur crée une transaction Paddle : la méthode PaddleGateway::createPaymentIntent() :
   • crée une transaction hors catalogue via l’API Paddle avec le montant, la devise et les métadonnées de la commande ;
   • stocke un enregistrement local paddle_transactions liant l’ID de transaction Paddle à la commande ;
   • lie le client Paddle à l’utilisateur local (si authentifié) ;
   • renvoie l’ID de transaction Paddle au front-end.
4. L’overlay Paddle.js s’ouvre : le JavaScript ouvre l’overlay de paiement Paddle en utilisant Paddle.Checkout.open() avec l’ID de transaction.
5. Le client finalise le paiement : le client saisit ses informations de paiement dans l’overlay Paddle.
6. Callback de paiement terminé : sur checkout.completed, le JavaScript redirige vers l’URL de retour (/paddle/return?_ptxn={transaction_id}).
7. Confirmation par l’URL de retour : la méthode PaddleController::return() appelle confirmPayment() pour vérifier le statut de la transaction via l’API Paddle. Si elle est terminée, la commande est marquée comme payée et le client est redirigé vers la page de succès.
8. Confirmation par webhook : Paddle envoie également un webhook transaction.completed comme sauvegarde fiable. Cela garantit que les commandes sont marquées comme payées même si le client ferme son navigateur avant la redirection de retour.

Gestion des webhooks

Les webhooks sont reçus sur POST /paddle/webhook. Ce point d’entrée est exclu de la protection CSRF et du middleware web.

Événements supportés

Vérification de signature

Tous les webhooks entrants sont vérifiés à l’aide de signatures HMAC-SHA256. Paddle envoie la signature dans l’en-tête HTTP Paddle-Signature au format :

Le processus de vérification :

1. Analyser les valeurs ts (horodatage) et h1 (hash) depuis l’en-tête.
2. Calculer HMAC-SHA256(timestamp + ':' + rawBody, webhookSecret).
3. Comparer le hash calculé avec la valeur h1 reçue en utilisant hash_equals().
4. Si la signature est invalide ou si le secret du webhook est vide, renvoyer une réponse 400.

Remboursements

L’add-on prend en charge les remboursements complets et partiels via l’API Paddle Adjustments.

Comment fonctionnent les remboursements

1. Un administrateur initie un remboursement depuis la page de gestion des commandes de la boutique.
2. La méthode PaddleGateway::refund() :
   • récupère la transaction Paddle pour obtenir les IDs des articles ;
   • crée un ajustement partiel avec Action::Refund() sur le premier article ;
   • crée un enregistrement shop_transactions de type refund.
3. Paddle traite le remboursement et envoie un webhook adjustment.created.
4. Le gestionnaire de webhook met à jour le statut de la commande en refunded si l’ajustement est approuvé.

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 les dépendances Composer

É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 → Paddle → Paramètres et confirmez que vos identifiants sont toujours configurés. Effectuez un paiement de test en mode sandbox 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 Paddle 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/paddle/. 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 Paddle 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/paddle/, public/vendor/paddle/ et storage/app/public/addons/paddle/ ;
• supprime le dossier de l’add-on extensions/addons/paddle/ ;
• 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/paddle/. 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

L’overlay de paiement Paddle ne s’ouvre pas

• Assurez-vous que le paddle_client_token est configuré dans les paramètres d’administration.
• Vérifiez la console du navigateur à la recherche d’erreurs JavaScript. Un jeton client manquant ou invalide affichera Paddle client token not configured.
• Vérifiez que le jeton correspond à l’environnement : les jetons sandbox commencent par test_, les jetons de production par live_.
• Assurez-vous que Paddle.js se charge : vérifiez que https://cdn.paddle.com/paddle/v2/paddle.js n’est pas bloqué par votre Content Security Policy ou par votre bloqueur de publicités.

Le paiement ne se confirme pas : la commande reste en “pending”

• Vérifiez que votre URL de webhook (/paddle/webhook) est accessible depuis Internet. Paddle doit pouvoir y envoyer des requêtes POST.
• Vérifiez que le paddle_webhook_secret est défini et correspond au secret de votre tableau de bord Paddle.
• Consultez storage/logs/laravel.log pour les erreurs liées aux webhooks.
• Dans le tableau de bord Paddle, sous Notifications, vérifiez si les livraisons de webhooks échouent.

Le webhook renvoie 400 : “Invalid signature”

• Le paddle_webhook_secret des paramètres d’administration ne correspond pas au secret du tableau de bord Paddle.
• Si vous avez récemment renouvelé le secret du webhook, mettez-le à jour dans les paramètres d’administration.
• Assurez-vous que le corps brut de la requête n’est pas modifié par un middleware avant la vérification de signature.

La création de transaction échoue : “Paddle transaction creation failed”

• Vérifiez que la paddle_api_key est correcte et n’a pas été révoquée.
• Assurez-vous que le paddle_seller_id est défini.
• Vérifiez que le code devise est valide et supporté par Paddle.
• Consultez les logs du serveur pour le message d’erreur complet de l’API Paddle.
• Si vous utilisez le sandbox, assurez-vous que la clé API est une clé sandbox (et non de production).

Le remboursement échoue : “Paddle refund failed”

• Vérifiez que la transaction d’origine était terminée (seules les transactions terminées peuvent être remboursées).
• Vérifiez que le montant du remboursement ne dépasse pas le montant de la transaction d’origine.
• Certains ajustements Paddle nécessitent une approbation manuelle : consultez le tableau de bord Paddle.
• Consultez les logs du serveur pour l’erreur détaillée de l’API Paddle.

La passerelle n’apparaît pas sur la page de paiement

• Assurez-vous que l’add-on Paddle est activé dans Admin → Add-ons.
• Assurez-vous que paddle_api_key et paddle_seller_id sont tous deux configurés (isAvailable() vérifie les deux).
• Vérifiez que l’add-on Boutique est actif (Paddle en dépend).

Le client n’est pas lié à un ID client Paddle

• La liaison du client se fait automatiquement lors de la création de la transaction, lorsque le payable a un ID utilisateur.
• Les paiements en tant qu’invité (sans utilisateur authentifié) ne créent pas d’enregistrement paddle_customers.
• Consultez les logs du serveur pour les avertissements de linkCustomer().

Les paramètres ne s’enregistrent pas : les identifiants apparaissent vides après la sauvegarde

• Les identifiants sont chiffrés avant le stockage et déchiffrés pour l’affichage. Si la APP_KEY a changé, les valeurs précédemment chiffrées ne peuvent pas être déchiffrées.
• Saisissez à nouveau tous les identifiants après un changement de APP_KEY.
• Vérifiez que la table settings est accessible en écriture.