Paddle est le fournisseur de paiement marchand-de-référence utilisé par de nombreuses entreprises SaaS européennes — Paddle gère la TVA européenne, la taxe de vente américaine, les remboursements, les rétrofacturations et la conformité internationale en votre nom, puis vous verse le montant net.

Connecter Paddle à Zenovay vous permet de voir les revenus Paddle aux côtés de vos données de trafic — quelles campagnes concluent la vente, quelles pages convertissent, quelles sources ont le meilleur LTV.

Vous n'avez besoin que d'UNE seule chose : une clé API Paddle avec permission d'écriture. Zenovay crée la destination webhook en votre nom, capture le secret de signature via l'API Paddle et les stocke tous les deux — de manière chiffrée. Le flux est identique que vous connectiez un environnement Sandbox ou Live ; vous sélectionnez simplement l'environnement correspondant avec le bouton Sandbox/Live sur le formulaire.

Configuration (2 minutes)

1
Générer une clé API avec permission d'écriture dans Paddle
- Live : vendors.paddle.com/authentication-v2
- Sandbox : sandbox-vendors.paddle.com/authentication-v2
Cliquez sur New API key → nommez-la "Zenovay analytics" → permission : Write → Create.
Paddle affiche la clé UNE seule fois. Copiez-la maintenant. Les clés Live commencent par pdl_live_apikey_… ; les clés sandbox par pdl_sdbx_apikey_….
2
Collez-la dans Zenovay et cliquez sur Save Configuration
1. Dans app.zenovay.com, ouvrez votre site depuis Domains, allez dans Settings et sélectionnez l'onglet Revenue.
2. Cliquez sur la carte Paddle.
3. Collez la clé API et réglez le bouton Sandbox/Live pour qu'il correspond (pdl_sdbx_apikey_… les clés sont Sandbox ; pdl_live_apikey_… les clés sont Live). Si le bouton et le préfixe de la clé ne correspondent pas, la connexion est rejetée avec un message d'erreur clair.
4. Cliquez sur Save Configuration.

C'est tout. En coulisses, Zenovay :

Valide la clé auprès de l'endpoint /event-types de Paddle.
Appelle POST /notification-settings pour créer une destination webhook à https://api.zenovay.com/api/webhooks/paddle/<votre-website-id> abonnée aux quatre événements canoniques (transaction.completed, subscription.created, subscription.updated, subscription.canceled).
Capture endpoint_secret_key depuis la réponse de Paddle et le stocke de manière chiffrée.
Bascule la carte sur Connected.

Vous ne touchez jamais au tableau de bord Paddle. Vous ne voyez ni ne copiez jamais de secret de signature. Chaque webhook de Paddle est vérifié à l'aide du secret stocké avant toute écriture en base de données.

« Où trouver mon secret de signature dans Paddle ? » — réponse courte : vous n'en avez pas besoin

C'est la confusion la plus fréquente. Paddle masque délibérément le secret de signature dans son tableau de bord après la création de la destination. Il n'y a pas de bouton « afficher », pas de lien « montrer » — seulement Rotate Secret (qui invalide l'ancien et vous en fournit un nouveau). Pour les comptes qui affichent le secret à la création, vous avez une brève fenêtre pour le copier avant qu'il disparaisse.

C'est le comportement normal de Paddle, pas un bug. Il existe pour une raison de sécurité : les secrets dans les interfaces utilisateur fuient via des captures d'écran, des tickets de support et des regards indiscrets.

C'est exactement pourquoi le flux de connexion de Zenovay ne vous demande pas de le trouver. Nous utilisons l'API Paddle (qui expose le secret par programmation pour vos propres destinations) pour le récupérer automatiquement. Vous n'y touchez jamais.

Et si j'avais déjà créé la destination manuellement ?

Pas de problème. Lorsque vous enregistrez la carte Paddle dans Zenovay :

Si une destination existe déjà à notre URL, Zenovay la réutilise et récupère le secret via l'API.
Si elle est actuellement inactive (par exemple, quelqu'un l'a désactivée dans l'interface Paddle), Zenovay la réactive.
Aucune destination dupliquée, aucun nettoyage manuel.

Et si je veux quand même la configurer manuellement ?

Vous pouvez, mais c'est une friction sans bénéfice. Si vous insistez :

Étapes de configuration manuelle (non recommandées)

Dans Paddle → Notifications → Destinations → New destination → Webhook.
URL : https://api.zenovay.com/api/webhooks/paddle/YOUR_WEBSITE_ID (votre ID de site est le UUID dans l'URL de la page lorsque vous ouvrez le site depuis Domains dans app.zenovay.com ; il apparaît également en haut de l'onglet Revenue des paramètres).
Abonnez-vous à tous les événements (Zenovay ignore silencieusement tout ce qu'il ne gère pas).
Enregistrez la destination.
C'est là où la plupart des gens bloquent : Paddle peut ou non afficher le secret de signature à l'écran suivant. S'il ne s'affiche pas :
- Option A : Faites pivoter le secret (Paddle → Destinations → cliquez sur votre destination → Rotate Secret). Copiez la nouvelle valeur.
- Option B : Supprimez cette destination et utilisez plutôt le flux de connexion de Zenovay (Zenovay la recréera et récupérera le secret via l'API).
Dans Zenovay → carte Paddle → ouvrez la section Advanced (optional) après avoir collé votre clé API → collez le secret de signature pdl_ntfset_… dans le champ Secret webhook.
Enregistrez.

Pour 99 % des utilisateurs, utilisez simplement le flux de connexion ci-dessus et ignorez cette procédure.

Étiquetez vos transactions avec l'ID visiteur (recommandé)

Pour que l'attribution paiement-vers-source-de-trafic fonctionne avec le maximum de précision, définissez l'ID anonyme Zenovay du visiteur comme custom_data lors de la création de la transaction ou du paiement Paddle sur votre serveur :

// Node.js example using Paddle's API directly
const visitorId = req.cookies['zv_visitor_id']; // however your client passes it

await fetch('https://api.paddle.com/transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PADDLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [{ price_id: 'pri_01h…', quantity: 1 }],
    customer_id: paddleCustomerId,
    custom_data: { zenovay_visitor_id: visitorId },
  }),
});

Lorsque la transaction se termine, Zenovay lit data.custom_data.zenovay_visitor_id et associe le paiement à la session du visiteur — y compris la source, la campagne et les pages visitées avant le paiement.

Si vous ne définissez pas custom_data, l'attribution fonctionne quand même via l'adresse e-mail du client (lorsqu'elle est présente sur l'événement), mais elle est moins précise — elle ne correspond que si le visiteur s'est précédemment identifié avec le même e-mail.

Quel modèle d'attribution est utilisé

Zenovay prend en charge deux fenêtres d'attribution :

Premier contact — le crédit va à la source depuis laquelle le visiteur est arrivé lors de sa première session.
Dernier contact — le crédit va à la source depuis laquelle il est arrivé lors de la session contenant le paiement.

Les deux sont calculés et affichés côte à côte dans l'onglet Revenue.

Étape 5 : Tests Sandbox

La bonne façon de vérifier votre intégration Sandbox est d'effectuer un vrai paiement test :

Dans le tableau de bord sandbox de Paddle, créez un produit + prix de test.
Utilisez une superposition de paiement ou une URL de paiement hébergée sur une page de test qui charge votre script de suivi Zenovay.
Finalisez le paiement avec l'un des numéros de carte de test de Paddle.
Dans les ~10 secondes : Paddle envoie un vrai événement transaction.completed signé à Zenovay. Vérifiez qu'il est arrivé en chargeant l'onglet Revenue dans Zenovay — la capture devrait apparaître avec l'e-mail de l'acheteur + le montant.

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

Vérifiez le badge Verification status sur la carte Paddle dans les paramètres de Zenovay.
Confirmez que le mode Sandbox vs Live correspond des deux côtés. Un tableau de bord Paddle en environnement Sandbox envoie des événements depuis sandbox-api.paddle.com ; si Zenovay est configuré en mode Live, la vérification de signature échouera.
Confirmez que la destination de notification est toujours activée dans Paddle (Paddle désactive automatiquement les destinations après 5 réponses 5xx consécutives ; si Zenovay était en cours de déploiement lors de votre test, réactivez-la).

Prise en charge des devises

Paddle retourne les montants des transactions dans la plus petite unité de la devise (par exemple, "4999" pour 49,99 USD). Zenovay effectue la conversion correctement selon ISO 4217 :

Devises décimales (USD, EUR, GBP, …) : divisé par 100 → 4999 devient 49,99.
Devises sans décimale (JPY, KRW, VND, …) : utilisé tel quel → 5000 JPY reste 5000.
Devises à trois décimales (BHD, KWD, OMR, …) : divisé par 1000 → 1500 BHD devient 1,500.

Vous n'avez rien à configurer — Zenovay effectue cela automatiquement en se basant sur currency_code dans l'événement.

Passer du Sandbox au Live

Lorsque vous êtes prêt pour la production :

Dans le tableau de bord Live de Paddle (vendors.paddle.com, pas sandbox-vendors), répétez les étapes 1 et 2 pour créer une destination de notification Live et une clé API Live.
Dans Zenovay, cliquez sur la carte Paddle → Disconnect (conserver l'historique est possible) → cliquez à nouveau pour reconnecter → collez les identifiants Live → basculez le bouton sur Live → Enregistrez.

La même URL webhook Zenovay fonctionne pour les deux environnements ; Paddle envoie les événements à la destination qui correspond à votre clé API active.

Déconnexion

Ouvrez votre site depuis Domains → Settings → l'onglet Revenue → cliquez sur la carte Paddle → Disconnect.

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

Optionnel : supprimer également les données Paddle historiques

La boîte de dialogue de déconnexion inclut une case à cocher : « Supprimer définitivement également N enregistrements Paddle (total X $) ». Cochez-la uniquement si vous souhaitez repartir de zéro — par exemple, pour désaffecter une intégration de test ou effectuer un nettoyage de confidentialité.

Lorsque cette option est cochée, Zenovay :

Supprime tous les événements de paiement Paddle pour ce site
Supprime tous les enregistrements de paiement Paddle pour ce site
Efface le champ ID client Paddle sur chaque utilisateur identifié (l'enregistrement utilisateur lui-même est préservé — il conserve son ID Stripe, etc.)

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

N'oubliez pas de désactiver la destination de notification côté Paddle

La déconnexion dans Zenovay ne fait qu'arrêter l'acceptation des événements par Zenovay. Paddle continuera à envoyer la destination à notre endpoint jusqu'à ce que vous la désactiviez dans votre tableau de bord Paddle :

Ouvrez Paddle → Notifications → Destinations.
Trouvez la destination pointant vers https://api.zenovay.com/api/webhooks/paddle/{your-website-id}.
Cliquez dessus → activez Disabled (ou Delete).

Jusqu'à ce que vous le fassiez, notre endpoint répond 400 "Webhook not configured for this website" à chaque livraison. Paddle finira par désactiver automatiquement la destination après suffisamment d'échecs — mais la suppression explicite est plus propre et évite que la destination encombre votre tableau de bord.

Limitations (V1)

Les événements de remboursement ne sont pas encore affichés. Abonnez-vous quand même à adjustment.created / adjustment.updated dans votre destination — Zenovay les ignore silencieusement aujourd'hui et commencera à les afficher dès que la V2 sera disponible.
Les événements subscription.past_due et subscription.paused sont reçus et enregistrés avec déduplication, mais ne sont pas encore affichés dans le tableau de bord. Le statut d'abonnement bascule correctement sur past_due, mais vous n'obtenez pas de vue d'incident dédiée.
Un compte Paddle par site Zenovay. Si vous acceptez des paiements via plusieurs comptes Paddle (par exemple, un par filiale géographique), configurez chacun sur son propre site Zenovay.
La connexion par redirection OAuth n'est pas prise en charge. Saisie manuelle des identifiants uniquement.

Dépannage

« Clé API Paddle invalide » à l'enregistrement

Trois suspects habituels :

Mauvais environnement. Une clé pdl_sdbx_apikey_… avec le bouton Live activé (ou vice versa) échoue à la validation. Zenovay affiche un message d'erreur spécifique — faites correspondre le bouton au préfixe.
La clé doit avoir la permission d'écriture ET ne pas être révoquée. Les clés en lecture seule passent la validation mais échouent lorsque Zenovay tente de créer la destination (403). Les clés révoquées échouent directement à la validation (401). Générez une nouvelle clé avec portée en écriture.
La clé appartenait à une équipe/compte différent. Les clés API Paddle sont limitées à un seul compte Paddle ; coller une clé d'un compte différent échoue immédiatement.

« Webhook not configured for this website »

Soit vous n'avez pas encore enregistré les identifiants Paddle dans Zenovay, soit vous testez la mauvaise URL webhook. L'URL doit inclure l'ID exact de site pour le site connecté (l'UUID dans l'URL de la page lorsque vous ouvrez le site depuis Domains dans app.zenovay.com).

« Signature verification failed: replay_window_exceeded »

Zenovay rejette les événements webhook dont l'horodatage s'écarte de plus de 5 minutes de l'heure actuelle. Cela signifie généralement un décalage d'horloge de votre côté ou de celui de Paddle. Si vous constatez cela lors d'un test récent :

Redémarrez votre serveur (la dérive d'horloge est rare mais se produit après un long temps de fonctionnement).
Déclenchez à nouveau le webhook depuis le tableau de bord Paddle (Notifications → Deliveries → Resend).

Un webhook vérifié arrive mais la transaction est absente de l'onglet Revenue

Le webhook Paddle arrive sous 3 formes distinctes selon que le client a été créé séparément ou dans le cadre d'un paiement. Le parseur de Zenovay est défensif, mais si vous constatez une livraison vérifiée dans vos journaux et rien dans Revenue :

Confirmez que la livraison a retourné un 2xx dans le journal de livraison de Paddle. Une inadéquation de signature ou d'environnement s'y affiche en tant que 4xx.
Si l'e-mail de l'acheteur manque dans l'événement, Zenovay revient à la correspondance par ID client Paddle. La transaction est enregistrée, mais elle n'apparaîtra pas dans les vues utilisateur identifié tant que le même client ne sera pas lié via un upsert d'utilisateur identifié ultérieur.
Si elle n'apparaît toujours pas, contactez le support à [email protected] avec l'ID de livraison Paddle pour que nous puissions le tracer.

Comment intégrer Paddle pour le suivi des revenus ?

Configuration (2 minutes)

Générer une clé API avec permission d'écriture dans Paddle

Collez-la dans Zenovay et cliquez sur Save Configuration