Intégration initiale avec Stripe

Adapty prend en charge les flows web2app en suivant les paiements web et les abonnements effectués via Stripe.

Cette intégration couvre les achats initiés depuis le web (Stripe Checkout, pages de paiement hébergées, Payment Links ou flows de paiement personnalisés) et les synchronise avec l’accès à l’application mobile et les analyses.

Elle est utile dans les cas suivants :

• Accorder automatiquement l’accès aux fonctionnalités payantes aux utilisateurs qui ont acheté depuis le web mais ont ensuite installé l’application et se sont connectés à leur compte
• Centraliser toutes les analyses d’abonnement dans un seul Adapty Dashboard (cohortes, prédictions et tout notre arsenal analytique)

Même si les achats web gagnent en popularité pour les applications, l’Apple App Store autorise un système différent des achats intégrés pour les biens numériques uniquement aux États-Unis. Veillez à ne pas promouvoir vos abonnements web dans votre application pour les autres pays. Dans le cas contraire, votre application risque d’être rejetée ou bannie.

Les étapes ci-dessous expliquent comment configurer l’intégration Stripe.

1. Connecter Stripe à Adapty

Cette intégration repose principalement sur la récupération des données d’abonnement depuis Stripe par Adapty via le webhook. Vous devez donc connecter votre compte Adapty à votre compte Stripe en fournissant des clés API et en utilisant l’URL du webhook d’Adapty dans Stripe. Pour automatiser la configuration de votre webhook, installez l’application Adapty dans Stripe :

0. Déterminez si vous connectez Stripe en mode test ou en mode live. Si vous faites cela d’abord en mode test, vous devrez répéter les étapes ci-dessous pour le mode live.

1. Rendez-vous sur le Stripe App Marketplace et installez l’application Adapty. Notez que le mode sandbox ne prend pas en charge l’installation d’applications. Vous pouvez uniquement le faire en mode production ou en mode test.

2. Accordez les autorisations requises à l’application. Cela permettra à Adapty d’accéder aux données d’abonnement et à l’historique. Cliquez ensuite sur Continue to app settings pour continuer.

En bas de la fenêtre contextuelle d’autorisation, vous pouvez choisir d’installer l’application en mode live ou test.

3. Dans la fenêtre contextuelle, générez une nouvelle clé restreinte. Vous devrez vérifier votre identité par e-mail, Touch ID ou clé de sécurité. Une fois la clé générée, vous ne pourrez plus la consulter, alors conservez-la en lieu sûr dans un gestionnaire de mots de passe ou un coffre-fort de secrets.

4. Copiez la clé générée depuis la fenêtre contextuelle et accédez à App Settings → Stripe dans Adapty. Collez la clé dans la section Stripe App Restricted API Key selon votre mode. Notez que vous devez générer des clés différentes pour les modes test et production.

C’est tout ! Créez ensuite vos produits sur Stripe et ajoutez-les à Adapty.

Flow d’installation obsolète

1. Accédez à Developers → API Keys dans Stripe :

2. Cliquez sur Reveal live (test) key button à côté du titre Secret key, puis copiez-la et rendez-vous dans App Settings → Stripe d’Adapty. Collez la clé ici :

3. Ensuite, copiez l’URL du Webhook depuis le bas de la même page dans Adapty. Rendez-vous dans Developers → Webhooks sur Stripe et cliquez sur le bouton Add endpoint :

4. Collez l’URL du webhook d’Adapty dans le champ Endpoint URL. Choisissez ensuite Latest API version dans le champ Version du webhook. Sélectionnez ensuite les événements suivants :

• charge.refunded
  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.deleted
  • customer.subscription.paused
  • customer.subscription.resumed
  • customer.subscription.updated
  • invoice.created
  • invoice.updated
  • payment_intent.succeeded

5. Cliquez sur “Add endpoint” puis sur “Reveal” sous “Signing secret”. C’est la clé utilisée pour décoder les données du webhook côté Adapty — copiez-la après l’avoir révélée :

6. Enfin, collez cette clé dans App Settings → Stripe d’Adapty, sous “Stripe Webhook Secret” :

2. Créer des produits sur Stripe

Rendez-vous dans le Catalogue de produits de Stripe et créez les produits que vous souhaitez vendre ainsi que leurs plans tarifaires. Notez que Stripe vous permet d’avoir plusieurs plans tarifaires par produit, ce qui est utile pour adapter votre offre sans avoir à créer des produits supplémentaires.

3. Ajouter des produits Stripe à Adapty

Nous traitons Stripe de la même manière qu’App Store et Google Play : c’est simplement un autre store où vous vendez vos produits numériques. La configuration est donc similaire : ajoutez simplement vos produits Stripe (c’est-à-dire leur product_id et leur price_id) dans la section Products d’Adapty :

Les IDs de produit dans Stripe ressemblent à prod_... et les IDs de prix ressemblent à price_.... Ils sont faciles à trouver pour chaque produit dans le Catalogue de produits Stripe, en ouvrant n’importe quel produit :

Une fois que vous avez ajouté tous les produits nécessaires, l’étape suivante consiste à indiquer à Stripe quel utilisateur effectue l’achat, afin qu’Adapty puisse le détecter !

4. Enrichissez les achats effectués sur le web avec votre identifiant utilisateur

Adapty s’appuie sur les webhooks de Stripe pour fournir et mettre à jour les niveaux d’accès des utilisateurs, qui constituent la seule source d’information. Toutefois, vous devez fournir des informations supplémentaires de votre côté lorsque vous travaillez avec Stripe pour que cette intégration fonctionne correctement.

Pour que les niveaux d’accès soient cohérents sur toutes les plateformes (web ou mobile), vous devez vous assurer qu’il existe un identifiant utilisateur unique sur lequel Adapty peut s’appuyer et qu’il reconnaît depuis les webhooks. Il peut s’agir de l’adresse e-mail, du numéro de téléphone ou de tout autre identifiant issu de votre système d’authentification. Adapty appelle cette valeur customer_user_id.

Adapty lit l’identifiant utilisateur depuis une seule source — celle sélectionnée dans Profile creation behavior dans App Settings → Stripe. Il ne s’agit pas d’une chaîne de substitution : si la source sélectionnée est vide pour une transaction donnée, l’achat reste anonyme même si l’identifiant est présent ailleurs dans les données Stripe. Voir Profile creation behavior pour toutes les sources disponibles.

Choisissez l’option qui correspond à la façon dont vous créez des achats dans Stripe.

Sessions de paiement et abonnements créés via l’API Stripe

Laissez Profile creation behavior sur Use customer_user_id from metadata (default). Ensuite, accédez à la partie de votre code qui initialise le paiement via Stripe — et ajoutez cet identifiant utilisateur à l’objet metadata de la Stripe Subscription (sub_...) ou de la Checkout Session (ses_...) sous la clé customer_user_id, comme ceci :

{'customer_user_id': "YOUR_USER_ID"}

Cet ajout est la seule modification à apporter dans votre code. Ensuite, Adapty traitera tous les webhooks reçus de Stripe, extraira ces metadata et associera correctement les abonnements à vos clients.

Liens de paiement (sans code)

Si vous vendez via Stripe Payment Links et n’avez pas de backend pour définir metadata, passez l’identifiant utilisateur dans le paramètre de requête client_reference_id du lien :

https://buy.stripe.com/your_link?client_reference_id=YOUR_USER_ID

Stripe stocke cette valeur dans la Checkout Session et la transmet à Adapty dans l’événement checkout.session.completed. Cela fonctionne aussi bien pour les abonnements que pour les achats uniques.

5. Accorder l’accès aux utilisateurs sur mobile

Pour vous assurer que vos utilisateurs mobiles arrivant depuis le web peuvent accéder aux fonctionnalités payantes, il vous suffit d’appeler Adapty.activate() ou Adapty.identify() avec le même customer_user_id que celui fourni à l’étape précédente (consultez Identification des utilisateurs iOS, Android, React Native, Flutter et Unity pour en savoir plus).

6. Testez votre intégration

Assurez-vous d’avoir effectué les étapes ci-dessus pour le Sandbox ainsi que pour la Production. Les transactions réalisées depuis le mode Test de Stripe seront considérées comme Sandbox dans Adapty.

Comportement lors de la création du profil

Adapty doit associer un achat à un profil client pour qu’il soit disponible sur mobile — par défaut, il crée des profils à la réception des webhooks de Stripe. Vous pouvez choisir ce qui sera utilisé comme identifiant utilisateur client dans Adapty :

1. Par défaut et recommandé : utiliser customer_user_id depuis les métadonnées — le customer_user_id que vous avez fourni dans les métadonnées à l’étape 4 ci-dessus
2. Utiliser l’e-mail de l’objet Customer de Stripe (voir la documentation Stripe)
3. Utiliser client_reference_id de l’objet Session de Stripe (voir la documentation Stripe) — l’option à utiliser avec les Payment Links

Vous pouvez configurer l’ID à utiliser dans App Settings → Stripe. Adapty utilise uniquement la source que vous sélectionnez ici pour chaque transaction Stripe dans l’application — il ne bascule pas vers les autres sources.

Vous avez également une quatrième option : ne pas créer de profils du tout, mais cette approche n’est pas recommandée en raison des limitations mentionnées ci-dessus dans Analytics.

Limitations actuelles

Mise à niveau, rétrogradation et prorata

Les modifications d’abonnement telles que les mises à niveau ou les rétrograddations peuvent entraîner des frais au prorata. Adapty ne prend pas en compte ces frais dans les calculs de revenus. Il est préférable de désactiver ces options manuellement via le tableau de bord Stripe. Vous pouvez également les désactiver en définissant la valeur de l’attribut proration_behaviour sur none via l’API Stripe.

Annulations

Stripe propose deux options d’annulation d’abonnement :

1. Annulation immédiate : l’abonnement est annulé immédiatement, avec ou sans option de proratisation.
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).

Adapty prend en charge ces deux options, mais le calcul des revenus pour une annulation immédiate ne tiendra pas compte de l’option de proratisation.

Problèmes de facturation et délai de grâce

Lorsqu’un client rencontre un problème de paiement, Adapty génère un événement de problème de facturation et l’accès est révoqué. Nous ne prenons pas encore en charge le délai de grâce de Stripe — cette fonctionnalité sera incluse dans de prochaines versions.

Remboursements

Adapty ne suit que les remboursements intégraux. Les remboursements au prorata ou partiels ne sont actuellement pas pris en charge.

Unicité des identifiants de transaction

Adapty associe les profils et les transactions via store_transaction_id et store_original_transaction_id. Ces identifiants doivent être uniques entre les environnements Test et Production.

Pourquoi c’est important

Si le même identifiant de transaction existe dans les deux environnements, Adapty les traite comme une seule transaction, ce qui entraîne :

• Les achats en Production héritent des niveaux d’accès et des identifiants produit de l’environnement Test
• Des identifiants produit et des environnements incorrects dans les réponses API
• Des problèmes de liaison des profils et d’événements d’abonnement

Comment garantir l’unicité

Les identifiants de facture Stripe peuvent se chevaucher entre les environnements Test et Live. Pour éviter les collisions entre environnements, choisissez l’une des approches suivantes

Option 1 : Numérotation au niveau du compte avec préfixes d’environnement

Configurez des préfixes séparément pour chaque environnement :

1. Dans le Stripe Dashboard, passez en mode Test.
2. Accédez à Settings → Billing → Invoices.
3. Définissez Invoice numbering sur Sequentially across your account.
4. Définissez Invoice prefix sur TEST- (ou un autre préfixe spécifique à l’environnement de test).
5. Passez en mode Live et répétez les étapes 2 à 4, en utilisant LIVE- (ou un autre préfixe spécifique à l’environnement de production) comme préfixe.

Option 2 : Numérotation au niveau du client

Dans les paramètres Stripe -> Billing -> onglet Invoices, définissez Invoice numbering sur Sequentially for each customer (customer-level).

Même avec la configuration ci-dessus, si vous supprimez une facture, Stripe peut réutiliser cet identifiant pour de nouvelles factures du même client. Il vaut mieux éviter de supprimer des factures autant que possible.

Achats uniques via Stripe Checkout ou Payment Links

Adapty enregistre les achats uniques (hors abonnement) effectués via Stripe Checkout (mode=payment) ou Payment Links à partir de l’événement checkout.session.completed. Assurez-vous que cet événement est activé sur votre endpoint webhook Adapty dans Stripe — les endpoints créés avant qu’Adapty ajoute la prise en charge des Payment Links ne l’incluent pas. Consultez l’étape 4 pour savoir comment vérifier.

Adapty récupère le produit à partir du premier élément de la session, donc une session qui vend plusieurs produits n’enregistre que le premier.

Les remboursements pour ces achats ne sont pas encore appliqués : Stripe envoie charge.refunded, mais Adapty ne révoque pas l’accès pour un achat unique effectué via Checkout ou un Payment Link. Les remboursements d’abonnements et d’achats uniques facturés via une facture Stripe fonctionnent normalement.

Exploitez davantage vos données Stripe

Une fois l’intégration avec Stripe effectuée, Adapty est prêt à fournir des insights immédiatement. Pour tirer le meilleur parti de vos données Stripe, vous pouvez configurer des intégrations Adapty supplémentaires afin de transférer les événements Stripe — centralisant ainsi toutes vos analyses d’abonnements dans un seul Adapty Dashboard.

{
  'customer_user_id': "YOUR_USER_ID",
  'variation_id': "YOUR_VARIATION_ID"
}

Intégrations que vous pouvez utiliser pour transférer et analyser vos événements Stripe :

• Amplitude
• Webhook
• Firebase
• Mixpanel
• Posthog

Événements Stripe pris en charge

Adapty prend en charge les événements Stripe suivants :

• charge.refunded
• checkout.session.completed
• customer.subscription.created
• customer.subscription.deleted
• customer.subscription.paused
• customer.subscription.resumed
• customer.subscription.updated
• invoice.created
• invoice.updated
• payment_intent.succeeded