Intégration Stripe

Stripe facture les clients de votre SaaS et signale chaque paiement par un webhook. Connecté à Traqio, votre compte Stripe rattache chaque facture payée, chaque renouvellement et chaque remboursement à l’utilisateur inscrit — une campagne est ainsi créditée de l’argent payé par ses inscrits, du premier au douzième mois, avec un seul appel serveur à l’inscription et aucun par paiement. C’est l’équivalent web de l’intégration RevenueCat, avec les mêmes règles pour les remboursements, les paiements de test et les doublons.

Mise en place#

1. Déclarez l’inscription une fois#

   Là où votre backend crée le compte, déclarez-le avec l’identifiant utilisateur et le trackID avec lequel le visiteur est arrivé — voir le SDK Node (PHP et Python fonctionnent pareil). L’e-mail est facultatif : le SDK le hache sur votre serveur et n’envoie que le hash, la clé de repli décrite plus bas.

   await traqio.signup({
     userId: user.id,
     trackId: trackIdFromRequest(req),
     email: user.email, // facultatif — haché localement, jamais envoyé
   });

2. Mettez l’identifiant dans les metadata Stripe#

   Renseignez metadata.traqio_user_id avec le même identifiant à la création de l’abonnement — Stripe recopie les metadata d’un abonnement sur chaque facture qu’il produit, renouvellements compris. Sur le client, cela fonctionne aussi.

   await stripe.subscriptions.create({
     customer: customerId,
     items: [{ price: priceId }],
     metadata: { traqio_user_id: user.id },
   });
   
   // Stripe Checkout :
   await stripe.checkout.sessions.create({
     mode: "subscription",
     subscription_data: { metadata: { traqio_user_id: user.id } },
     // …
   });

3. Créez une clé restreinte#

   Tableau de bord Stripe → Développeurs → Clés API → Créer une clé restreinte. Réglez Clients : Lecture, Factures : Lecture et Endpoints de webhook : Écriture ; laissez tout le reste sur Aucun. Une clé de production (rk_live_…) mesure les vrais paiements ; une clé de test (rk_test_…) permet d’essayer le branchement avec des paiements de test uniquement.

4. Collez-la dans Traqio#

   Dans la console : votre produit → Intégrations → Revenus → Stripe. Traqio lit un client et une facture pour prouver la clé, puis crée son endpoint de webhook dans votre compte Stripe — URL https://api.traqio.app/webhooks/stripe/<id du produit> — et garde son secret de signature. Une clé refusée par Stripe n’est pas enregistrée, et le message nomme la permission à cocher.

   Pas de permission Endpoints de webhook ?

   Ajoutez l’endpoint vous-même dans Stripe → Développeurs → Webhooks, avec l’URL affichée dans la console et les événements listés plus bas, cochez « J’ai ajouté l’endpoint de webhook moi-même » et collez son secret de signature (whsec_…) avec la clé.

5. Faites un paiement en mode test#

   Avec une clé de test, un paiement en mode test apparaît dans les Événements Stripe récents de la console comme Mode test — branchement vérifié, avec le montant lu par Traqio. Il n’est jamais compté. Les paiements de production sont ceux qui comptent ; chaque ligne dit à quel utilisateur il a été crédité, ou pourquoi il n’est pas rattaché.

Comment un paiement retrouve son utilisateur#

Traqio essaie dans cet ordre, et s’arrête à la première réponse :

Un paiement qu’aucun ne rattache à un utilisateur est non rattaché : enregistré, compté dans le revenu du produit, crédité à aucune campagne. Un identifiant que Traqio ne connaît pas encore — le paiement est arrivé avant l’appel d’inscription — est conservé, et le paiement rejoint l’utilisateur quand l’inscription arrive.

Ce que fait chaque événement Stripe#

• Devise : chaque paiement est gardé dans la devise payée, et converti dans la devise de reporting du produit au taux du jour dans les rapports.
• Doublons : un événement Stripe est traité une fois, et un paiement est indexé sur son identifiant de facture — une relivraison, ou la même facture aussi déclarée par votre serveur avec transactionId, c’est une seule ligne. Voir Compter un achat une seule fois.
• Remboursements : ils ne sont retirés que de paiements que Traqio a enregistrés : une facture payée avant la connexion de Stripe n’a jamais été ajoutée, son remboursement ne retire donc rien.
• Montants bruts : ce que le client a payé, taxes comprises ; la part de taxe est stockée, pas appliquée. Les frais Stripe ne sont pas déduits.

Limites#

• Traqio compte les factures. Un paiement Checkout ponctuel compte quand sa session crée une facture (invoice_creation.enabled) ; un PaymentIntent seul, sans facture, ne compte pas.
• Un compte Stripe par produit Traqio. Un compte Stripe qui vend plusieurs produits envoie tous leurs paiements à chaque produit connecté, où les clients des autres apparaissent non rattachés.
• Les paiements du site sont attribués et affichés dans Traqio, mais pas encore envoyés à Meta ni à TikTok.

Questions fréquentes#

Pourquoi une clé restreinte plutôt qu’une connexion Stripe Connect ?

Une clé restreinte fonctionne sur n’importe quel compte Stripe dès sa création, et elle est plus étroite : elle lit les clients et les factures, et peut créer un endpoint de webhook. Elle ne peut ni encaisser, ni rembourser, ni rien modifier. Traqio refuse une clé secrète complète (sk_…) et stocke la clé restreinte chiffrée.

Traqio écrit-il quelque chose dans mon compte Stripe ?

Une seule chose : l’endpoint de webhook qu’il crée pour lui-même, décrit comme celui de Traqio. Déconnecter Stripe dans la console le supprime. Rien d’autre n’est écrit, et aucun objet d’argent n’est jamais touché.

Et si un paiement ne nomme aucun utilisateur ?

C’est quand même du revenu : il est enregistré et compté dans le total du produit, comme non rattaché — il n’atteint aucune campagne. Traqio n’attribue jamais un paiement au hasard, et la liste des événements Stripe dit pourquoi chaque paiement n’est pas rattaché.

Dois-je encore appeler track() à chaque paiement ?

Non. Avec Stripe connecté, signup() est le seul appel serveur. Si vous gardez un track() pour un paiement Stripe, passez l’identifiant de facture (in_…) en transactionId avec store: "stripe" : les deux remontées tombent sur une seule ligne.