1. Objectif et périmètre d’utilisation
WebPoint - Abonnements PayPal permet de vendre des produits à paiement récurrent (abonnements) via PayPal sur votre boutique PrestaShop. Le module gère :
- La création automatique des Products & Plans côté PayPal
- Le checkout PayPal pour souscription
- La réception des webhooks (renouvellements, échecs, annulations)
- L'espace client pour gérer ses abonnements
- Un back-office complet (liste, filtres, export CSV, statistiques)
- Une API publique pour vérifier un abonnement depuis un script externe
2. Démarrage rapide
Étape 1. Allez dans Configuration API, renseignez votre Client ID et Secret PayPal, choisissez le mode (Sandbox ou Live) et cliquez Tester la connexion.
Étape 2. Toujours dans Configuration API, cliquez sur Créer le webhook chez PayPal. Le webhook sera enregistré automatiquement.
Étape 3. Allez dans Produits / Plans, choisissez un produit PrestaShop, configurez fréquence + prix + essai, puis sauvegardez. Le module crée automatiquement le Plan PayPal.
Étape 4. Sur la fiche produit en front, le bouton S'abonner avec PayPal apparaît. Faites un test en mode Sandbox.
Étape 5. Vérifiez dans Abonnements que la souscription apparaît bien avec le statut ACTIVE.
3. Configuration PayPal
Récupérer Client ID & Secret
- Connectez-vous sur
developer.paypal.com
- Menu Apps & Credentials
- Onglet Sandbox (pour tests) ou Live (production)
- Cliquez Create App, donnez-lui un nom (ex : "PrestaShop Subs")
- Copiez le
Client ID et le Secret dans la configuration du module
Sandbox vs Live : Toujours commencer en Sandbox. Les comptes de test se créent depuis Sandbox → Accounts sur developer.paypal.com.
4. Créer un produit avec abonnement
Dans l'onglet Produits / Plans, sélectionnez un produit PrestaShop existant et configurez :
| Champ |
Description |
| Fréquence |
Mensuel, trimestriel, semestriel, annuel |
| Prix |
Montant prélevé à chaque cycle (devise de la boutique) |
| Essai gratuit |
Nombre de jours d'essai (0 = pas d'essai) |
| Frais d'inscription |
Montant unique facturé au démarrage |
| Cycles |
Nombre total de cycles. 0 = sans engagement (jusqu'à annulation) |
Important : PayPal ne permet pas de modifier librement un Plan déjà créé. Si vous changez le prix, créez un nouveau produit ou désactivez l'ancien plan.
5. Webhooks PayPal
Les webhooks permettent à PayPal de notifier votre boutique en temps réel des événements suivants :
BILLING.SUBSCRIPTION.ACTIVATED — abonnement activéBILLING.SUBSCRIPTION.CANCELLED — abonnement annuléBILLING.SUBSCRIPTION.SUSPENDED — abonnement suspenduPAYMENT.SALE.COMPLETED — paiement de renouvellement reçuPAYMENT.SALE.DENIED — paiement échoué
Le module crée automatiquement le webhook côté PayPal lorsque vous cliquez Créer le webhook. L'URL utilisée est :
https://votre-boutique.com/module/paypalsubscriptions/webhook
Simulateur PayPal : Le simulateur de webhooks PayPal ne génère pas de signature valide. Les vrais événements de production fonctionnent normalement.
6. Espace client
Dans son compte client, l'utilisateur voit une nouvelle tuile Mes abonnements PayPal. Il y trouve :
- La liste de tous ses abonnements (actifs, suspendus, annulés)
- Les actions : Suspendre, Réactiver, Annuler définitivement
- L'historique des paiements avec lien vers la facture PDF
- Les dates de prochaine facturation
7. API publique (pour script externe)
Une API JSON permet à un script externe (ex: votre application SaaS) de vérifier si un client a un abonnement actif.
URL et clé
Récupérez l'URL et la clé API dans Configuration API → API publique. Vous pouvez régénérer la clé à tout moment.
Exemple cURL
curl "https://votre-boutique.com/module/paypalsubscriptions/api?key=VOTRE_CLE&email=client@example.com"
Exemple PHP
$url = 'https://votre-boutique.com/module/paypalsubscriptions/api'
. '?key=' . urlencode($apiKey)
. '&email=' . urlencode($email);
$response = json_decode(file_get_contents($url), true);
if ($response['authorized'] === true) {
// L'utilisateur a un abonnement actif
}
Réponse JSON
{
"authorized": true,
"subscription": {
"id": 12,
"status": "ACTIVE",
"product": "Plan Pro",
"next_billing_date": "2026-05-08"
}
}
8. Statistiques & KPI
| Indicateur |
Définition |
| Abonnements actifs |
Nombre d'abonnements en statut ACTIVE |
| MRR |
Monthly Recurring Revenue — revenu mensuel récurrent estimé |
| Revenu total |
Somme de tous les paiements reçus |
| Taux d'attrition |
Churn rate — % d'abonnés perdus sur le mois |
| Nouveaux abonnements (12 mois) |
Graphique d'évolution mensuelle |
| Revenu mensuel (12 mois) |
Graphique du chiffre encaissé par mois |
9. Emails de relance (dunning)
Le module envoie automatiquement des emails au client pour les événements suivants :
- Paiement échoué — fichier
mails/fr/payment_failed.html
- Abonnement suspendu — fichier
mails/fr/subscription_suspended.html
- Abonnement annulé — fichier
mails/fr/subscription_cancelled.html
Vous pouvez personnaliser ces templates dans International → Traductions → Traductions des emails.
10. Multi-boutique
Le module est compatible multi-boutique. Chaque plan et chaque abonnement est rattaché à une boutique via la colonne id_shop. Les listes et statistiques sont filtrées par boutique active.
11. Dépannage
Erreur "invalid_api_key" sur l'API
Vérifiez que la clé est copiée intégralement (sans espace). Régénérez-la si besoin depuis l'onglet Configuration.
Webhook signature failed
Si l'erreur vient du simulateur PayPal, c'est normal (signatures de test invalides). En production réelle, ça fonctionne.
Statut PENDING qui reste bloqué
Le client a quitté PayPal sans valider. Le module nettoie automatiquement ces lignes orphelines à la prochaine annulation.
"undefined" sur PrestaShop 9
Problème connu lié au système de nouvelles traductions PS9. Utiliser l'URL CRON en attendant.
Le bouton S'abonner ne s'affiche pas
Vérifier que le produit a bien un Plan associé dans Produits / Plans, et que ce plan est actif.
12. Compatibilité
- PrestaShop : 1.7.x, 8.x, 9.x
- PHP : 7.4, 8.0, 8.1, 8.2, 8.3
- API PayPal : REST v1 (
/v1/billing/*)
- Dépendances : aucune (cURL natif, pas de Composer)
WebPoint
