--- title: "Intégration initiale avec Paddle" description: "Intégrez Paddle avec Adapty pour un traitement fluide des paiements d'abonnement." --- > **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skill. Claude Code (self-updating via plugin): `claude plugin marketplace add adaptyteam/adapty-sdk-integration-skill && claude plugin install adapty-sdk-integration@adapty` — other tools: `npx skills add adaptyteam/adapty-sdk-integration-skill --all` Adapty prend en charge les flows web2app en suivant les paiements et abonnements effectués via [Paddle](https://www.paddle.com/). Cette intégration couvre les achats initiés sur le web et les synchronise avec l'accès à l'application mobile et les analytics, aux côtés des achats intégrés depuis les stores. Elle est utile dans les cas suivants : - Centraliser les données d'abonnement des achats intégrés et des achats effectués sur votre site web dans un seul système - Accorder l'accès aux fonctionnalités payantes de votre application mobile aux utilisateurs qui ont acheté sur votre site web - Consulter les analytics et les données d'abonnement de tous vos canaux de vente dans un seul tableau de bord :::note Apple autorise désormais les applications de l'App Store américain à inclure des liens vers des systèmes de paiement externes, même si les applications peuvent encore être tenues de proposer des achats intégrés en parallèle. Consultez les directives App Store en vigueur pour votre région et catégorie d'application. ::: :::note Cette intégration porte sur le suivi et la synchronisation des achats web Paddle. Si vous devez rediriger des utilisateurs depuis l'application vers une page de paiement web, utilisez les [paywalls web](web-paywall) d'Adapty. ::: Pour configurer l'intégration Paddle, suivez ces étapes : ## 1\. Connecter Paddle à Adapty \{#1-connect-paddle-to-adapty\} L'intégration utilise des webhooks pour envoyer les données d'abonnement de Paddle vers Adapty. Pour connecter vos comptes Adapty et Paddle, vous devrez : 1. Fournir vos clés API Paddle. 2. Ajouter l'URL webhook d'Adapty dans Paddle. :::note Les étapes ci-dessous s'appliquent à la fois à la Production et au Test. Vous pouvez configurer les deux simultanément. Les liens fournis correspondent à l'environnement de Production — pour obtenir les liens de l'environnement de Test, ajoutez simplement `sandbox-` au début de chaque URL. Par exemple, utilisez `https://sandbox-vendors.paddle.com/authentication-v2` au lieu de `https://vendors.paddle.com/authentication-v2`. ::: ### 1.1. Obtenir et ajouter les clés API Paddle \{#11-get-and-add-paddle-api-keys\} 1. Dans Paddle, allez dans [Developer Tools → Authentication](https://vendors.paddle.com/authentication-v2) et cliquez sur **New API key**. 2. Donnez un nom à la clé et définissez sa date d'expiration. Pour que la clé API fonctionne avec Adapty, vous devez lui accorder la permission **Read** pour toutes les entités. Cliquez sur **Save**. 3. Cliquez sur **Copy key**. 4. Dans Adapty, allez dans [App Settings → Paddle](https://app.adapty.io/settings/paddle) et collez la clé dans la section **Paddle API key**. :::warning Si vous avez défini une date d'expiration pour votre clé API Paddle, vous devez générer manuellement une nouvelle clé et la mettre à jour dans Adapty avant son expiration. L'intégration cessera de fonctionner sans avertissement à l'expiration de la clé, et les utilisateurs ne pourront plus effectuer d'achats. ::: ### 1.2. Ajouter les événements à envoyer à Adapty \{#12-add-events-that-will-be-sent-to-adapty\} 1. Copiez l'**URL Webhook** depuis la même page **Paddle** dans Adapty. 2. Dans Paddle, allez dans [**Developer Tools → Notifications**](https://vendors.paddle.com/notifications-v2) et cliquez sur **New destination** pour ajouter un webhook. 3. Saisissez un nom descriptif pour le webhook. Nous recommandons d'y inclure « Adapty » afin de le retrouver facilement si nécessaire. 4. Collez l'**URL Webhook** d'Adapty dans le champ **URL**. Veillez à utiliser le webhook correspondant au bon environnement. 5. Définissez le **Notification type** sur **Webhook**. 6. Sélectionnez les événements suivants : - `subscription.created` - `subscription.updated` - `transaction.created` - `transaction.updated` - `adjustment.created` - `adjustment.updated` 7. Cliquez sur **Save destination** pour finaliser la configuration du webhook. ### 1.3. Récupérer et ajouter la clé secrète du webhook \{#13-retrieve-and-add-the-webhook-secret-key\} 1. Dans la fenêtre **Notifications**, cliquez sur les trois points à côté du webhook que vous venez de créer et sélectionnez **Edit destination**. 2. Un nouveau champ appelé **Secret key** apparaîtra dans le panneau **Edit destination**. Copiez-le. 3. Dans Adapty, allez dans [App Settings → Paddle](https://app.adapty.io/settings/paddle) et collez la clé dans le champ **Notification secret key**. Cette clé est utilisée pour vérifier les données webhook dans Adapty. ### 1.4. Associer les clients Paddle aux profils Adapty \{#14-match-paddle-customers-with-adapty-profiles\} Adapty doit lier chaque achat à un [profil client](profiles-crm) pour pouvoir l'utiliser dans votre application. Par défaut, les profils sont créés automatiquement lorsqu'Adapty reçoit des webhooks de Paddle. Vous pouvez choisir quelle valeur utiliser comme `customer_user_id` dans Adapty : 1. **Par défaut et recommandé :** Le `customer_user_id` que vous transmettez dans le champ `custom_data` (voir la [documentation Paddle](https://developer.paddle.com/build/transactions/custom-data)) 2. L'`email` de l'objet Paddle Customer (voir la [documentation Paddle](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open/#parameters)) 3. L'identifiant Paddle Customer au format `ctm-...` (voir la [documentation Paddle](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open/#parameters)) 4. Ne pas créer de profils. Choisissez cette option si vous souhaitez avoir plus de contrôle sur vos profils clients et les gérer vous-même. Vous pouvez configurer la valeur à utiliser dans le champ **Profile creation behavior** dans [App Settings → Paddle](https://app.adapty.io/settings/paddle). ## 2. Ajouter les produits Paddle à Adapty \{#2-add-paddle-products-to-adapty\} :::warning Assurez-vous d'ajouter vos produits Paddle à l'Adapty Dashboard ou d'ajouter un identifiant de produit Paddle à vos produits existants. Adapty ne suit que les événements pour les transactions liées à ces produits. Si vous sautez cette étape, aucun événement de transaction ne sera créé. ::: Paddle fonctionne dans Adapty comme l'App Store et Google Play — c'est une autre plateforme sur laquelle vous vendez des produits numériques. Pour le configurer, ajoutez les valeurs `product_id` et `price_id` correspondantes depuis Paddle dans la section [Products](https://app.adapty.io/products) d'Adapty. Dans Paddle, les identifiants de produit ressemblent à `pro_...` et les identifiants de prix à `pri_...`. Vous les trouverez dans votre [catalogue de produits Paddle](https://vendors.paddle.com/products-v2) en ouvrant un produit spécifique : Une fois vos produits ajoutés, l'étape suivante consiste à s'assurer qu'Adapty peut associer l'achat au bon utilisateur. ## 3\. Accorder l'accès aux utilisateurs sur mobile \{#3-provide-access-to-users-on-the-mobile\} Pour que les utilisateurs qui achètent sur le web bénéficient de l'accès sur mobile, appelez `Adapty.activate()` ou `Adapty.identify()` avec le même `customer_user_id` que celui utilisé lors de l'achat. Consultez [Identification des utilisateurs](identifying-users) pour plus de détails. ## 4\. Tester votre intégration \{#4-test-your-integration\} Une fois tout configuré, vous pouvez tester votre intégration. Les transactions effectuées dans l'environnement de Test de Paddle apparaîtront comme **Test** dans Adapty. Les transactions de l'environnement de Production apparaîtront comme **Production**. Votre intégration est maintenant terminée. Les utilisateurs peuvent souscrire des abonnements sur votre site web et accéder automatiquement aux fonctionnalités premium dans votre application mobile, pendant que vous suivez toutes les analytics d'abonnement depuis votre Adapty Dashboard unifié. ## Considérations importantes \{#important-considerations\} - Dans les analytics d'Adapty, les montants des transactions incluent les taxes et les frais Paddle, ce qui diffère du tableau de bord Paddle où les montants sont affichés après taxes et frais. Les chiffres que vous verrez dans Adapty seront donc plus élevés que ceux de votre tableau de bord Paddle. - Contrairement aux autres stores, les remboursements dans Paddle n'affectent que la transaction spécifique remboursée et n'annulent pas automatiquement l'abonnement. L'abonnement restera actif à moins d'être explicitement annulé. - Vous pouvez également inclure `variation_id` dans le champ `custom_data` pour attribuer les achats à des instances de paywall spécifiques. Adapty traitera ces données depuis les webhooks et les inclura dans les analytics. ### Essais payants \{#paid-trials\} Lorsque vous travaillez avec des essais payants dans Paddle, vous devez créer deux produits dans Adapty : 1. Créez un produit non-abonnement et associez-le au prix Paddle qui facture la période d'essai. 2. Créez ensuite un produit d'abonnement (Mensuel/Hebdomadaire/etc.) et associez-le au prix Paddle qui comporte la composante d'essai gratuit. Du point de vue de Paddle, il s'agit d'un seul produit avec deux prix dans une seule transaction — un prix pour la facturation de l'essai (par exemple, 0,99 $) et un autre pour l'essai gratuit (0,00 $). Du point de vue d'Adapty, cela crée deux événements distincts : un achat unique pour le paiement de l'essai et un événement de démarrage d'essai pour le produit d'abonnement. Par exemple, lorsqu'un utilisateur commence un essai payant à 0,99 $ pour un abonnement à 9,99 $/mois, Paddle crée une transaction avec les deux prix, tandis qu'Adapty traite cela comme un achat unique de 0,99 $ (paiement immédiat) et un événement de démarrage d'essai à 0,00 $ (futur abonnement à 9,99 $/mois). :::note Lorsque des utilisateurs annulent un essai payant, vous recevez les événements **Trial expired** et **Trial renewal canceled**. ::: ## Exploitez davantage vos données Paddle \{#get-more-from-your-paddle-data\} :::important Pour que vos événements Paddle fonctionnent avec les intégrations, vos utilisateurs doivent s'être connectés à l'application avec leur compte App Store/Google Play au moins une fois. ::: Une fois intégré à Paddle, Adapty est prêt à fournir des insights immédiatement. Pour tirer le meilleur parti de vos données Paddle, vous pouvez configurer des intégrations Adapty supplémentaires pour transférer les événements Paddle — en centralisant toutes vos analytics d'abonnement dans un seul Adapty Dashboard. Intégrations disponibles pour transférer et analyser vos événements Paddle : - [AppsFlyer](appsflyer) - [Webhook](webhook) - [Posthog](posthog) ## Limitations actuelles \{#current-limitations\} - **Annulations** : Paddle propose deux options d'annulation d'abonnement : 1. Annulation immédiate : l'abonnement est annulé immédiatement. 2. Annulation en fin de période : l'abonnement est annulé à la fin de la période de facturation en cours (similaire aux abonnements intégrés sur les stores). - **Remboursements** : Adapty suit les remboursements complets et partiels. - **Délai de grâce** : Par défaut, Paddle applique un délai de grâce fixe de 30 jours pour les problèmes de facturation, pendant lequel l'abonnement reste actif. Vous pouvez [personnaliser la durée du délai de grâce et l'action après son expiration (suspension ou annulation de l'abonnement)](https://developer.paddle.com/build/retain/configure-payment-recovery-dunning#prerequisites). **Essais** : Si le prélèvement échoue après la fin d'un essai, le statut de l'abonnement passe à `past_due`. En production, Paddle Retain applique une fenêtre de relance pour tenter de récupérer le paiement avant d'annuler ou de suspendre l'abonnement. En sandbox, Retain n'est pas disponible, donc aucune nouvelle tentative de paiement n'est effectuée et l'abonnement reste `past_due` indéfiniment. --- **Voir aussi :** - [Valider un achat dans Paddle, obtenir un niveau d'accès et importer l'historique des transactions depuis Paddle via l'API server-side](api-adapty/operations/validatePaddlePurchase)