Guide du module Portefeuille (Crédits) pour Larapen

Un système de crédits fondamental, propre à chaque utilisateur. Il donne à chaque utilisateur un solde de crédits adossé à un registre de transactions immuable, vend des crédits via des packs de recharge ponctuels et des formules d’abonnement récurrentes, et expose une API unique WalletService::spend() que tous les add-ons d’outils IA/SaaS utilisent pour facturer leur utilisation.

Cas d’utilisation

Plateforme d’outils IA / SaaS

Vous proposez une suite d’outils consommateurs de crédits (créateur de logos, suppression d’arrière-plan, portraits IA, outils vidéo).

• Le portefeuille fournit le solde partagé dans lequel puise chaque outil.
• Chaque outil déclare ses actions et un coût par défaut ; vous ajustez les prix de façon centralisée dans Tarification des actions.
• Les utilisateurs rechargent à la carte ou souscrivent une allocation mensuelle.

Produit axé sur l’abonnement

Vous voulez des revenus récurrents avec une allocation mensuelle de crédits prévisible.

• Créez des formules (par ex. Starter / Creator / Pro) avec des crédits mensuels et un prix annuel moins cher facultatif.
• Les crédits sont distribués chaque mois, même en facturation annuelle, et sont remis à zéro à chaque cycle (non reportables).
• Les utilisateurs annulent ou reprennent eux-mêmes leur abonnement depuis leur page de portefeuille.

Add-on en paiement à l’usage

Vous n’avez besoin que d’achats ponctuels, sans abonnement.

• Créez uniquement des packs de recharge ; laissez la liste des formules vide.
• Accordez éventuellement un bonus de bienvenue pour que les nouveaux comptes puissent essayer les outils avant de payer.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur (requires_core: >=1.0.0)
• PHP 8.3+
• MySQL 8.0+
• Le portefeuille nécessite un compte utilisateur (needs_user_account: true) : les soldes sont propres à chaque utilisateur.
• Au moins un add-on de passerelle de paiement pour encaisser réellement de l’argent (voir ci-dessous).

Installation

Étape 1 : Placer & activer l’add-on

Copiez le dossier wallet (ou créez un lien symbolique) dans extensions/addons/, puis activez-le depuis Admin → Add-ons (ou exécutez php artisan addons:sync). L’activation enregistre les permissions et le menu d’administration.

Étape 2 : Exécuter les migrations

php artisan migrate

Cela crée six tables préfixées par wallet_ : wallet_accounts, wallet_packs, wallet_orders, wallet_transactions, wallet_plans et wallet_subscriptions.

Étape 3 : Créer des offres de départ (facultatif)

php artisan db:seed --class="Addons\Wallet\Database\Seeders\WalletSeeder"

Crée trois formules d’abonnement (Starter / Creator / Pro, mensuelles + annuelles à prix réduit) et un pack de recharge ponctuel. Le seeder est idempotent (firstOrCreate).

Étape 4 : Attribuer les permissions

L’add-on enregistre ses permissions sous l’espace de noms wallet.*. Attribuez-les aux rôles via Admin → Rôles & permissions.

Étape 5 : Créer des formules et/ou des packs

Définissez vos offres dans Portefeuille → Formules d’abonnement et/ou Portefeuille → Packs de recharge (ou utilisez le seeder). Dirigez ensuite vos utilisateurs vers la page publique du portefeuille /wallet (ajoutez-la à la navigation de votre site en tant que lien de menu personnalisé).

Code d’achat (clé de licence)

Portefeuille de crédits n’est pas vendu séparément : il est livré avec les produits qui en ont besoin, son activation ne demande donc pas de code d’achat propre. Le code d’achat dont vous avez besoin est celui du produit que vous avez réellement acheté : l’application principale, ou l’add-on ou le thème payant qui inclut Portefeuille de crédits. Cette page explique où trouver ce code.

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?

Le modèle de crédits

Chaque compte portefeuille contient deux réserves de crédits distinctes :

Chaque modification d’un solde écrit une transaction immuable dans le registre, avec le solde courant balance_after enregistré, de sorte que l’historique peut être audité sans avoir à le rejouer.

Configuration

Les paramètres se gèrent dans Admin → Portefeuille → Paramètres (stockés dans la table settings). Les valeurs par défaut du fichier de configuration se trouvent dans config/wallet.php ; les paramètres en base de données les remplacent à l’exécution.

Autres valeurs par défaut disponibles uniquement dans le fichier de configuration config/wallet.php : credits_expire (par défaut false), credit_expiry_days (par défaut null) et auto_create_account (par défaut true : un compte portefeuille est créé au premier accès). Les taux et paliers de la formule de tarification ont aussi des valeurs par défaut dans config/wallet.php, sous la clé formula (remplacées champ par champ par les paramètres wallet_formula_*).

La page de paramètres propose aussi les options standard de personnalisation de l’En-tête de page (mode hero / simple) pour les pages publiques du portefeuille.

Admin : Tableau de bord

Le tableau de bord (Portefeuille → Tableau de bord) donne une vue d’ensemble de l’économie du portefeuille.

Cartes de statistiques

• Comptes portefeuille : nombre d’utilisateurs disposant d’un portefeuille.
• Crédits en circulation : total des crédits utilisables sur l’ensemble des comptes.
• Crédits achetés (au total) et Crédits dépensés (au total).
• Commandes payées et Chiffre d’affaires issus des achats de recharges.

Activité récente

Les panneaux Commandes récentes et Utilisation récente (consommation) vous permettent de repérer les derniers achats et les dernières dépenses sans quitter le tableau de bord.

Le tableau de bord affiche aussi le lien de la page publique (/wallet) pour que vous puissiez l’ajouter à la navigation de votre site en tant que lien de menu personnalisé.

Admin : Comptes

Les comptes se gèrent dans Portefeuille → Comptes. La liste affiche chaque portefeuille utilisateur avec son utilisateur, son solde, le total acheté et le total dépensé.

Détail d’un compte

L’ouverture d’un compte affiche ses soldes et l’historique complet des transactions de cet utilisateur.

Ajustement manuel du solde

Depuis un compte, un administrateur disposant de wallet.accounts.adjust peut ajouter ou retirer des crédits, avec un motif facultatif enregistré sur l’écriture du registre.

Admin : Transactions (registre)

Le registre global, dans Portefeuille → Transactions, est une liste paginée en lecture seule de tous les mouvements de crédits sur l’ensemble des comptes. Chaque ligne affiche l’utilisateur, un badge de type, le montant signé, le solde après opération, la clé d’action (pour les consommations et remboursements), la description et la date.

Types de transactions

Admin : Packs de recharge

Les packs de recharge sont des lots de crédits ponctuels. Ils se gèrent dans Portefeuille → Packs de recharge, avec une liste AJAX et une fenêtre modale de création/modification.

Un slug d’URL unique est attribué automatiquement à partir du nom et utilisé dans les URL de paiement.

Admin : Formules d’abonnement

Les formules récurrentes accordent une allocation mensuelle de crédits. Elles se gèrent dans Portefeuille → Formules d’abonnement (liste AJAX + fenêtre modale de création/modification).

Les identifiants de produit/prix de la passerelle sont créés automatiquement à partir de vos formules lors du premier paiement (et recréés lorsque le prix d’une formule change). Vous n’avez pas à les créer à la main dans la passerelle.

Lorsque la Formule de tarification est activée, les champs Prix mensuel et Prix annuel sont masqués et calculés à partir des crédits mensuels de la formule et du paramètre de réduction annuelle.

Admin : Commandes de recharge

Les commandes se gèrent dans Portefeuille → Commandes. Chaque paiement de recharge crée une ligne de commande. La liste affiche le numéro de commande, l’utilisateur, un badge de statut, la passerelle, le montant et les crédits. L’ouverture d’une commande affiche son détail complet et la ou les transactions associées.

Statuts de commande

Les commandes implémentent le contrat BillableForInvoice de la plateforme : les recharges payées peuvent donc alimenter le système de facturation du noyau.

Admin : Tarification des actions

Dans Portefeuille → Tarification des actions, choisissez un groupe d’outils/service et définissez le coût en crédits de chacune de ses actions. Les add-ons d’outils déclarent leurs actions (et un coût par défaut) dans leur manifeste ; cet écran vous permet de modifier le prix de chaque outil depuis un seul endroit, sans toucher au code.

• Laissez un champ vide pour utiliser le coût par défaut de l’add-on pour cette action.
• Les valeurs personnalisées sont lues par chaque outil via le registre d’actions partagé au moment de la facturation.

Admin : Paramètres

La page de paramètres (Portefeuille → Paramètres) est organisée en onglets :

• Libellés des crédits : libellé au singulier / au pluriel de la monnaie virtuelle.
• Solde & bonus : devise par défaut des packs, seuil de solde bas, bonus de bienvenue pour les nouveaux comptes, et catégories de FAQ à afficher sur la page de tarifs.
• Page de tarifs : combiner formules & packs dans la disposition à trois cartes (ou conserver deux sections séparées et choisir laquelle vient en premier), et masquer éventuellement la page de tarifs aux invités.
• Formule de tarification : passer à la tarification calculée et configurer les taux & paliers (voir Formule de tarification).
• Paiement : Conditions de vente du paiement des recharges de crédits. Par défaut, les conditions de vente globales (Paramètres → Général → Conditions de vente) s’appliquent ; activez Remplacer les conditions de vente globales pour exiger (ou non) l’acceptation d’une page précise, uniquement sur le paiement des recharges et sur l’étape de confirmation de l’abonnement.
• En-tête de page : personnalisation de l’en-tête hero / simple des pages publiques du portefeuille.

Voir Configuration pour la référence complète des clés.

Admin : Formule de tarification

Au lieu de saisir chaque prix à la main, l’onglet Formule de tarification vous permet de définir quelques valeurs et de générer le prix de chaque pack & formule : le modèle classique de la “grille tarifaire” (le prix par crédit baisse à mesure que le volume augmente). Il est facultatif : le mode est par défaut sur Manuel, rien ne change donc tant que vous ne l’activez pas.

Un tableau d’aperçu en direct affiche les prix que vos packs & formules actuels obtiendraient avec la formule au fil de vos modifications (avant l’enregistrement). L’enregistrement en mode Formule, ou le bouton Recalculer maintenant, recalcule et enregistre le prix de chaque pack & formule actif.

Exemple (valeurs par défaut) : un taux de base de 0.02/crédit avec −10 % à 5 000 et −25 % à 10 000, arrondi psychologique → 1 000 crédits = $19.99, 5 000 = $89.99 (+1 000 de bonus), 10 000 = $149.99 (+2 500 de bonus).

Front-end : Mon portefeuille

Les pages publiques du portefeuille sont destinées aux utilisateurs finaux connectés. Elles sont localisées (par ex. /fr/wallet), avec des variantes non localisées pour la langue par défaut.

Routes

Tableau de bord du portefeuille

• Solde actuel : la somme des crédits permanents + d’abonnement, avec un avertissement de solde bas le cas échéant.
• Panneau Votre formule : affiché lorsque l’utilisateur a un abonnement, avec la date de renouvellement/de fin et les boutons Annuler / Reprendre.
• Activité récente : les dernières écritures du registre, avec un lien vers l’historique complet.

Front-end : Recharge & abonnement

La page de tarifs (/wallet/pricing) présente à la fois les formules d’abonnement et les packs ponctuels. Par défaut, elle est visible par les invités (ils ne se connectent qu’au moment d’acheter ou de s’abonner) ; les paramètres Page de tarifs permettent de la masquer aux invités. Chaque carte payante affiche un coût par crédit (par ex. $ 0.0190 USD/Credit), et un pack à 0 apparaît comme une carte gratuite Essai gratuit.

Dispositions

• Séparée (par défaut) : une section Abonnement et une section Packs ponctuels. Le paramètre Ordre des sections détermine laquelle vient en premier.
• Combinée (mixte) : trois cartes (Essai gratuit, Abonnement et Paiement à l’usage), où les cartes Abonnement et Paiement à l’usage utilisent une liste déroulante pour changer de palier sur place (à la manière d’online-convert).

Abonnements

• Un sélecteur mensuel / annuel bascule tous les prix des formules (et affiche l’économie annuelle).
• S’abonner ouvre une étape de confirmation (/wallet/subscribe/{plan}?interval=monthly|yearly, connexion requise) : le récapitulatif de la formule et, si nécessaire, les conditions de vente à accepter (voir l’onglet de paramètres Paiement). Continuer vers le paiement sécurisé envoie ensuite l’utilisateur vers la page de paiement hébergée de la passerelle.
• Après le paiement, le webhook de la passerelle active l’abonnement et accorde la première allocation mensuelle.

Packs ponctuels

• Chaque pack affiche ses crédits (plus un éventuel bonus) et son prix.
• Acheter maintenant ouvre une page de paiement avec un récapitulatif de commande et le choix du moyen de paiement.
• Une fois le paiement réussi, les crédits sont ajoutés instantanément au solde permanent et l’utilisateur est renvoyé vers une page de confirmation.

Parcours de paiement (packs)

Abonnements Stripe

La facturation récurrente est gérée par la passerelle Stripe. Configurez-la comme suit.

Étape 1 : Clés d’API

Ajoutez vos clés Stripe dans .env (les noms lus par la configuration de l’add-on Stripe) :

STRIPE_PUBLIC_KEY=pk_test_xxx
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

Étape 2 : Point de terminaison du webhook

Dans Stripe, ajoutez un webhook pointant vers :

https://YOUR_DOMAIN/wallet/webhook/subscription/stripe

Abonnez-le aux événements suivants :

Pour les tests en local : stripe listen --forward-to https://YOUR_DOMAIN/wallet/webhook/subscription/stripe.

Planificateur de crédits

L’allocation mensuelle est distribuée par une commande Artisan quotidienne. Assurez-vous que le planificateur de Laravel s’exécute via une seule entrée cron système :

* * * * * cd /path/to/app && php artisan schedule:run >> /dev/null 2>&1

L’add-on enregistre cette tâche (quotidienne, withoutOverlapping, onOneServer) :

php artisan wallet:grant-subscription-credits

Elle accorde l’allocation mensuelle à chaque abonnement actif dont le versement est dû et dont la période payée le couvre encore. Vous pouvez l’exécuter manuellement à tout moment pour créditer les abonnements arrivés à échéance.

Notifications

L’add-on fournit deux types de notifications destinées aux utilisateurs, enregistrés de façon centralisée via addon.json et activables ou désactivables dans Admin → Paramètres → Notifications.

Mise à jour

Méthode 1 : Téléversement depuis le panneau d’administration (recommandé)

1. Téléchargez le dernier .zip de l’add-on.
2. Allez dans Admin → Add-ons et cliquez sur Téléverser.
3. Sélectionnez le .zip. Une confirmation affiche les numéros de version actuel et nouveau ; cliquez sur Remplacer.
4. Allez dans Admin → Mise à jour du système (/admin/update) pour appliquer les migrations en attente.

Méthode 2 : Remplacement manuel des fichiers

1. Remplacez le dossier extensions/addons/wallet par la nouvelle version.
2. Exécutez php artisan migrate.
3. Videz les caches : php artisan config:clear, view:clear, route:clear.

Désinstallation

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

La page de recharge n’affiche aucun pack ni aucune formule

• Assurez-vous qu’au moins un pack ou une formule existe et est marqué comme actif, ou exécutez le seeder.
• Les formules n’affichent une option annuelle que lorsqu’un prix annuel est défini ; sinon, elles sont uniquement mensuelles.

“Aucun moyen de paiement n’est disponible” lors du paiement

• Installez et configurez au moins un add-on de passerelle de paiement (stripe, paypal, paddle, momo) pour les packs ponctuels.
• Les abonnements nécessitent spécifiquement la passerelle Stripe.

Abonnement payé mais aucun crédit n’est apparu

• Vérifiez que le webhook Stripe est enregistré sur /wallet/webhook/subscription/stripe et abonné à customer.subscription.created.
• Vérifiez que STRIPE_WEBHOOK_SECRET correspond au secret de signature du point de terminaison.
• Consultez storage/logs/laravel.log pour repérer les erreurs de webhook.

Les crédits mensuels ne se renouvellent pas

• Assurez-vous que le cron système exécute php artisan schedule:run chaque minute.
• Exécutez php artisan wallet:grant-subscription-credits manuellement pour créditer les abonnements arrivés à échéance.
• Les crédits ne sont accordés que tant que l’abonnement est actif et que sa période payée couvre encore la distribution.

Un utilisateur a été débité pour une génération échouée

• Les outils doivent facturer via WalletService::spend(), qui rembourse automatiquement en cas d’échec. Un appel direct à debit() sans spend() englobant ne rembourse pas automatiquement : vérifiez l’intégration de l’add-on d’outils.

Notification de recharge non reçue

• Vérifiez que wallet_topup_received est activé dans Paramètres → Notifications et que l’utilisateur ne l’a pas refusé.
• Vérifiez votre configuration de messagerie dans .env et consultez la table failed_jobs.