Comment intégrer PayPal pour le suivi des revenus ?

Connecter PayPal permet à Zenovay d'afficher les revenus aux côtés de vos données de trafic — quelle source marketing a produit le client payant, sur quelle page il a converti, quelle campagne a conclu l'affaire.

Vous avez besoin de trois choses depuis votre compte PayPal Developer : un Client ID, un Client Secret et un Webhook ID. Vous créez le webhook dans votre tableau de bord PayPal (Zenovay vous montre l'URL exacte à coller) et copiez son ID dans Zenovay. Nous recommandons de configurer Sandbox d'abord pour vérifier que tout fonctionne, puis de basculer en Live.

⚠️ Important — conseil de test à lire en premier

Le Webhooks Simulator de PayPal (le bouton « Send Test » dans le PayPal Developer Dashboard) envoie des événements simulés qui ne peuvent pas être vérifiés par signature par conception. Il s'agit d'un comportement documenté de PayPal — le simulateur lie les signatures à un WEBHOOK_ID factice, et non à votre véritable Webhook ID, donc l'API de vérification renvoie toujours FAILURE pour les événements du simulateur.

Pour vérifier que votre intégration fonctionne réellement, effectuez un véritable checkout Sandbox (Étape 5 ci-dessous) — cela produit un événement correctement signé que Zenovay peut vérifier.

Étape 1 : créer une application REST API PayPal — et activer la fonctionnalité Webhooks

⚠️ Activez la fonctionnalité Webhooks sur votre application.

Les nouvelles applications REST API PayPal sont par défaut configurées sur « Accept payments only ». Votre application a besoin de la fonctionnalité Webhooks activée pour pouvoir créer et vérifier les webhooks. C'est une configuration unique de 30 secondes.

1. 1

   Se connecter à PayPal Developer

   Allez sur developer.paypal.com et connectez-vous avec votre compte PayPal business. Gratuit ; cela prend environ une minute.

2. 2

   Ouvrir Apps & Credentials

   Dans le tableau de bord, cliquez sur Apps & Credentials. Basculez sur Sandbox pour les tests, ou Live pour la production.

3. 3

   Créer une nouvelle application

   Cliquez sur Create App. Nommez-la par exemple « Zenovay Analytics ». Choisissez Merchant comme type d'application. Cliquez sur Create App.

4. 4

   Copier votre Client ID et Secret

   PayPal affiche votre Client ID (longue chaîne alphanumérique) et Secret (cliquez sur Show pour le révéler). Gardez cet onglet ouvert — vous les collerez dans Zenovay à l'Étape 3.

5. 5

   Cocher la case de la fonctionnalité Webhooks

   Toujours sur la page de paramètres de votre application, faites défiler jusqu'à la section Features (parfois libellée App settings). Vous verrez des cases comme Accept payments, Vault, Payouts, Subscriptions, Log in with PayPal et Webhooks.

   Cochez la case Webhooks, puis cliquez sur Save Changes au bas de la page.

   Pas besoin de régénérer votre Client Secret — la nouvelle permission s'applique immédiatement aux nouveaux jetons OAuth.

Étape 2 : créer le webhook dans PayPal et copier son Webhook ID

Ouvrez les paramètres de votre site dans Zenovay et allez à l'onglet Revenue (sous la section Analytics), puis cliquez sur la carte PayPal. Le formulaire affiche une URL webhook copiable qui inclut déjà l'ID de votre site — copiez-la, puis enregistrez le webhook du côté PayPal.

1. 1

   Copier votre URL webhook Zenovay

   Dans la carte PayPal dans Zenovay, copiez l'URL webhook affichée en haut du formulaire. Elle ressemble à :

   https://api.zenovay.com/api/webhooks/paypal/YOUR_WEBSITE_ID
   

   L'URL est déjà remplie avec l'ID de votre site — vous n'avez pas besoin de la construire vous-même.

2. 2

   Ajouter le webhook dans PayPal

   De retour dans PayPal Developer, à l'intérieur des paramètres de votre application, faites défiler jusqu'à Sandbox Webhooks (ou Live Webhooks). Cliquez sur Add Webhook et collez l'URL que vous avez copiée.

3. 3

   S'abonner aux bons événements

   Cochez au minimum :

   • Payment capture completed
   • Payment capture refunded
   • Checkout order approved (optionnel ; journalisé pour l'observabilité)

   Cliquez sur Save. PayPal génère un Webhook ID — conservez-le pour l'Étape 3.

Étape 3 : se connecter dans Zenovay

Toujours sur la carte PayPal dans l'onglet Revenue de vos paramètres de site :

1. 1

   Coller vos trois identifiants

   • Client ID — depuis l'Étape 1
   • Client Secret (c'est le champ API Key) — depuis l'Étape 1
   • Webhook ID — l'ID que PayPal a généré à l'Étape 2 (requis)
2. 2

   Choisir Sandbox ou Live

   Faites correspondre l'environnement que vous avez configuré à l'Étape 1. Sandbox utilise api-m.sandbox.paypal.com ; Live utilise api-m.paypal.com. Mélanger les modes fera échouer la vérification de signature.

3. 3

   Cliquer sur Save

   Zenovay valide vos identifiants en récupérant un jeton d'accès OAuth2, puis vérifie le Webhook ID contre PayPal. La carte bascule sur Connected.

Étape 4 : taguer vos commandes avec l'ID visiteur (recommandé)

Pour que l'attribution paiement-vers-source-de-trafic fonctionne le plus précisément possible, définissez l'ID anonyme Zenovay du visiteur comme custom_id lors de la création de la commande PayPal sur votre serveur :

// Exemple Node.js utilisant @paypal/paypal-server-sdk
const visitorId = req.cookies['zv_visitor_id']; // ou comme votre client le passe

await paypalClient.ordersCreate({
  body: {
    intent: 'CAPTURE',
    purchase_units: [{
      amount: { currency_code: 'USD', value: '42.00' },
      custom_id: visitorId, // ← l'UUID visiteur Zenovay va ici
    }],
  },
});

Lorsque la capture se termine, Zenovay lit purchase_units[0].custom_id et joint le paiement à la session du visiteur — y compris la source, la campagne et les pages qu'il a visitées avant de payer.

Si vous ne définissez pas custom_id, l'attribution fonctionne toujours via l'adresse e-mail du payeur, mais elle est moins précise (correspond uniquement si le visiteur s'est précédemment identifié avec le même e-mail).

Comment fonctionne l'attribution

Zenovay attribue chaque paiement à une source de trafic et vous permet de basculer entre plusieurs modèles d'attribution depuis l'onglet Revenue :

• Last Touch (par défaut) — 100% du crédit va au dernier canal avant la conversion. Bon pour mesurer ce qui conclut les affaires.
• First Touch — 100% du crédit va au canal qui a d'abord amené le visiteur. Bon pour mesurer ce qui génère la découverte.
• Linear — répartit le crédit uniformément entre tous les canaux utilisés par le visiteur.
• Position-Based — 40% au premier canal, 40% au dernier, les 20% restants répartis entre tous les intermédiaires.
• Time-Decay — plus de crédit aux canaux plus proches de la conversion, sur une demi-vie de 7 jours.

Vous choisissez le modèle dans l'onglet Revenue ; la répartition se recalcule pour le modèle que vous choisissez.

Étape 5 : tests Sandbox — utilisez un vrai checkout, pas le Simulateur

N'utilisez pas le Webhooks Simulator de PayPal pour tester. Les événements du simulateur ne peuvent volontairement pas être vérifiés par signature (PayPal le documente) — ils échoueront toujours à la vérification de Zenovay. Utilisez plutôt un véritable checkout Sandbox, comme décrit ci-dessous.

La bonne façon de vérifier votre intégration Sandbox :

1. PayPal Developer Dashboard → Sandbox → Accounts. Vous devriez voir un compte sandbox Personal (buyer) par défaut avec un faux e-mail + mot de passe — ce sont les identifiants de l'acheteur de test.
2. Depuis votre application ou le SDK PayPal, créez une commande sandbox pointant vers votre client_id sandbox (définissez purchase_units[0].custom_id = visitorId si vous voulez la meilleure attribution — voir l'Étape 4 ci-dessus).
3. Complétez le checkout avec le compte acheteur sandbox de l'étape 1.
4. En environ 10 secondes, PayPal envoie un véritable webhook signé PAYMENT.CAPTURE.COMPLETED à Zenovay. Vérifiez qu'il est arrivé en ouvrant l'onglet Revenue sur votre tableau de bord de site — la capture devrait apparaître avec l'e-mail sandbox de l'acheteur + le montant.

Si la capture n'apparaît pas après environ 30 secondes :

• Vérifiez le badge Verification status sur la carte PayPal dans vos paramètres Revenue — il affiche l'erreur la plus récente.
• Confirmez que le mode Sandbox vs Live correspond : un webhook Sandbox déclenché contre une intégration Live (ou vice versa) fera échouer la vérification de signature.
• Confirmez que le webhook est toujours enregistré dans PayPal : PayPal Dashboard → votre application → Webhooks. S'il a été supprimé, rajoutez-le et collez le nouveau Webhook ID dans Zenovay.

Passer de Sandbox à Live

Lorsque vous êtes prêt pour la production :

1. Dans PayPal Developer, créez une application REST API Live et un Webhook Live (Étape 1 + Étape 2 à nouveau sur l'onglet Live — le webhook Live obtient son propre Webhook ID).
2. Dans Zenovay, ouvrez la carte PayPal, collez les identifiants Live et le Webhook ID Live, basculez le sélecteur sur Live, cliquez sur Save.

PayPal envoie les événements à l'environnement qui correspond au Webhook ID enregistré, gardez donc les identifiants et le Webhook ID du même environnement ensemble.

Déconnexion

Ouvrez les paramètres de votre site → onglet Revenue → cliquez sur la carte PayPal → Disconnect.

Par défaut, la déconnexion supprime uniquement vos identifiants PayPal. Vos enregistrements de paiements existants, votre historique d'attribution et les données du tableau de bord Revenus restent intacts (selon la fenêtre de conservation de votre plan). Vous pouvez vous reconnecter à tout moment et reprendre là où vous vous êtes arrêté.

Optionnel : également supprimer les données historiques PayPal

La boîte de dialogue de déconnexion comprend une case à cocher : « Supprimer également définitivement N enregistrements PayPal (X € au total) ». Cochez-la uniquement si vous voulez repartir de zéro — par exemple, pour mettre hors service une intégration de test ou faire le ménage de confidentialité.

Lorsque cochée, Zenovay :

• supprime toutes les lignes payment_events PayPal pour ce site
• supprime toutes les lignes payments PayPal pour ce site
• vide le champ paypal_customer_id sur chaque utilisateur identifié (l'enregistrement utilisateur lui-même est préservé — il garde son ID Stripe, etc.)

La suppression s'exécute dans une seule transaction — si une étape échoue, les trois sont annulées, donc vous ne vous retrouvez jamais dans un état à moitié supprimé. L'action est irréversible.

N'oubliez pas de supprimer le webhook côté PayPal

Se déconnecter dans Zenovay arrête uniquement la réception d'événements par Zenovay. PayPal continuera à envoyer le webhook vers notre endpoint jusqu'à ce que vous le supprimiez dans votre PayPal Developer Dashboard :

1. Ouvrez https://developer.paypal.com/dashboard/applications/
2. Cliquez sur votre application PayPal REST API.
3. Ouvrez la section Webhooks.
4. Trouvez le webhook pointant vers https://api.zenovay.com/api/webhooks/paypal/{your-website-id} et supprimez-le.

Tant que vous ne l'avez pas supprimé côté PayPal, notre endpoint répondra 410 Gone à chaque livraison. PayPal abandonne les nouvelles tentatives après 410 — c'est donc principalement cosmétique, mais c'est une bonne hygiène et évite que le webhook encombre les logs de retry de PayPal.

Limitations

• Un compte PayPal par site Zenovay. Si vous acceptez des paiements via plusieurs comptes PayPal, configurez chacun sur son propre site Zenovay.
• La connexion est saisie manuelle uniquement. Il n'y a pas de redirection OAuth « Log in with PayPal » — vous collez les Client ID, Client Secret et Webhook ID directement.

Dépannage

« Verification failed » sur un véritable webhook de test

Le plus probable est un décalage Sandbox/Live — le webhook déclenché par sandbox.paypal.com contre des identifiants marqués Live (ou vice versa) échouera à la vérification de signature. Vérifiez que le sélecteur sur la carte PayPal correspond à l'environnement de vos identifiants.

Si vous avez utilisé le Webhooks Simulator de PayPal, c'est une limitation connue — les événements du simulateur ne peuvent pas être vérifiés par signature par conception (PayPal lie la signature à un littéral WEBHOOK_ID factice, et non à votre véritable Webhook ID). Testez toujours avec un véritable checkout Sandbox à la place.

« NOT_AUTHORIZED » / erreur 403

Cela signifie généralement que la fonctionnalité Webhooks n'est pas activée sur votre application REST API PayPal, ou vous utilisez un compte sandbox Personal où les webhooks nécessitent un compte sandbox Business.

Correction :

1. Ouvrez https://developer.paypal.com/dashboard/applications et cliquez sur votre application.
2. Assurez-vous d'être sur le bon onglet (Sandbox ou Live) — ils ont des paramètres séparés.
3. Faites défiler jusqu'à la section Features (sous le bloc Client ID / Secret).
4. Cochez la case Webhooks.
5. Cliquez sur Save Changes au bas de la page.
6. Si vous êtes sur Sandbox, confirmez que vous utilisez un compte sandbox Business, pas un compte Personal.

Vous n'avez pas besoin de régénérer le Client Secret. La nouvelle permission s'applique immédiatement aux nouveaux jetons OAuth.

Limite de 10 webhooks atteinte sur votre application PayPal

PayPal limite chaque application REST API à 10 webhooks. Si vous avez enregistré Zenovay sur de nombreux sites Zenovay, vous pouvez atteindre cette limite. Supprimez les webhooks inutilisés à https://developer.paypal.com/dashboard/applications, puis ajoutez un nouveau webhook et collez son ID dans le site Zenovay pertinent.

Lectures complémentaires

• Intégration des revenus Stripe
• Vue d'ensemble des webhooks
• Suivi des revenus e-commerce
• Installer le script de suivi