Introduction
Dub est une plateforme d’attribution des liens pour les liens courts, le suivi des conversions et les programmes d’affiliation. Avec cette intégration, Dub enregistre un événement de conversion de vente chaque fois qu’un client paie via Dodo Payments, afin que vous puissiez mesurer le retour de vos campagnes marketing et de vos programmes de parrainage. Dub enregistre une vente lorsqu’un client :- Effectue un paiement ponctuel
- Souscrit à une offre payante
- Effectue un paiement d’abonnement récurrent
Cette intégration nécessite un compte Dub avec le suivi des conversions activé sur vos liens. Le suivi des conversions de Dub nécessite un forfait Business ou supérieur.
How It Works
Lorsqu’un visiteur clique sur l’un de vos liens courts Dub, Dub enregistre un identifiant de clic unique dans le cookiedub_id. Pour attribuer les ventes à vos liens :
- Capturez l’identifiant de clic de Dub depuis le cookie
dub_idlors de la création du checkout. - Stockez l’identifiant de clic dans le
metadatadu paiement, avec l’identifiant de votre client dans votre système (l’identifiant externe). - Envoyez la vente à Dub via son Track API lorsque le paiement réussit.
Prerequisites
Avant de configurer cette intégration, vous devez disposer des éléments suivants :- Un compte Dub avec un espace de travail.
- Le suivi des conversions activé pour vos liens.
- Une clé API Dub, que vous créez dans votre tableau de bord Dub sous Settings → API Keys.
Getting Started
1
Enable Conversion Tracking in Dub
Dans votre tableau de bord Dub, activez le suivi des conversions pour les liens dont vous souhaitez suivre les ventes. Dub enregistre alors les événements de vente pour les clients arrivant via ces liens.
Pour activer le suivi des conversions, consultez la documentation Dub.
2
Get Your Dub API Key
Dans votre tableau de bord Dub, accédez à Settings → API Keys et créez une clé API avec l’étendue
conversions.write.3
Capture Click ID in Checkout
Lors de la création d’un checkout, lisez l’identifiant de clic Dub dans le cookie et ajoutez-le au
metadata du paiement. Consultez l’étape 1.4
Send Sale Data via Webhook
Créez un endpoint webhook qui envoie chaque vente au Track API de Dub lorsqu’un paiement réussit. Consultez l’étape 2.
5
Done
Les événements de conversion des ventes apparaissent dans votre tableau de bord d’analytics Dub, attribués à vos liens.
Implementation Guide
Step 1: Add Click ID and Customer ID to Checkout Metadata
Lors de la création d’un checkout, lisez l’identifiant de clic Dub dans le cookie et incluez-le dans lemetadata du paiement, avec l’identifiant externe de votre client.
Les exemples ci-dessous utilisent
POST /payments, qui est obsolète. Il fonctionne toujours pour les intégrations existantes, mais les nouvelles intégrations doivent utiliser les Checkout Sessions (POST /checkouts), qui acceptent metadata de la même manière.Étape 2 : Envoyer les données de vente à Dub
Créez un endpoint webhook qui envoie les données de vente au Track API de Dub lorsqu’un paiement réussit.1
Open the Webhook Section
Dans le tableau de bord Dodo Payments, accédez à Developer → Webhooks, puis cliquez sur Add endpoint.

2
Select Dub
Dans Integration, sélectionnez Dub.co.
3
Enter API Key
Dans API key, collez votre clé API Dub. Dodo Payments l’envoie dans l’en-tête 
Authorization de chaque livraison.
4
Check the URL and Events
Si Endpoint URL est vide, saisissez
https://api.dub.co/track/sale. Dans Subscribed events, sélectionnez les événements gérés par votre transformation, tels que payment.succeeded.5
Configure Transformation
Sous Transformation code, modifiez le handler afin de formater les données de paiement pour l’API Track Sale de Dub. Commencez par les exemples.
6
Test & Create
Sous Test this code, cliquez sur Simulate pour exécuter le handler avec un exemple de payload. Cliquez ensuite sur Create endpoint.
Exemples de code de transformation
Chaque handler envoie une vente à Dub uniquement lorsquemetadata possède un identifiant de clic. Pour le trafic organique, lorsqu’il n’y a pas d’identifiant de clic, il définit webhook.cancel = true afin qu’aucune requête ne soit envoyée à Dub ; la livraison annulée apparaît tout de même comme réussie dans les journaux des webhooks.
Le corps de la requête suit l’API Track Sale de Dub : customerExternalId et amount sont obligatoires, et paymentProcessor est custom, car la liste des processeurs de paiement de Dub ne contient aucune valeur Dodo Payments. Dub prend amount dans la même unité que les montants Dodo Payments : en centimes pour les devises à deux décimales et sous forme d’entier complet pour les devises sans décimales, telles que JPY. Les exemples transmettent le montant sans modification.
Suivi basique des ventes
Suivez une vente lorsqu’un paiement aboutit :basic_sale.js
Suivi des ventes par abonnement
Suivez les abonnements initiaux et les paiements récurrents. Utilisez ce handler pour les abonnements à la place des handlerspayment.succeeded, et non en complément : chaque paiement d’abonnement déclenche également payment.succeeded, ce qui enregistrerait chaque vente deux fois. Consultez le guide d’intégration des abonnements.
Le handler lit l’identifiant de clic depuis le metadata de l’abonnement ; transmettez donc les mêmes métadonnées lors de la création de l’abonnement. Pour les renouvellements, invoiceId combine l’ID de l’abonnement avec previous_billing_date, le début de la période de facturation actuelle, afin qu’une livraison réessayée réutilise le même invoiceId.
subscription_sale.js
Suivi des ventes hors taxes
Envoyez uniquement le montant avant taxes à Dub afin que le chiffre d’affaires dans Dub exclue les taxes :sale_without_tax.js
Suivi des ventes avec des noms d’événements personnalisés
Utilisez des noms d’événements personnalisés pour catégoriser différents types de ventes. L’exemple lit un indicateuris_upgrade que vous définissez dans le metadata du paiement :
custom_events.js
Alternative : implémentation côté client
Pour suivre les ventes depuis votre propre serveur plutôt qu’au moyen d’une transformation de webhook, appelez directement l’API Track de Dub après un paiement réussi, par exemple depuis votre handler de webhookpayment.succeeded. Le code utilise votre clé API Dub ; exécutez-le donc sur votre serveur, jamais dans le navigateur.
Bonnes pratiques
- Incluez l’identifiant de clic dans les métadonnées : sans l’identifiant de clic, Dub ne peut pas attribuer le chiffre d’affaires à vos liens.
- Utilisez les ID externes de manière cohérente : transmettez systématiquement le même ID client de votre système en tant que
customerExternalIdpour obtenir des analyses précises au niveau du client. - Gérez le trafic organique : définissez
webhook.cancel = truelorsqu’il n’y a pas d’identifiant de clic afin d’éviter les appels API inutiles. - Testez avec des paiements d’exemple : exécutez le handler avec Test this code et confirmez que l’intégration fonctionne avant la mise en production.
- Surveillez votre tableau de bord Dub : vérifiez que les ventes apparaissent avec l’attribution attendue.
Remarques importantes
- Format du montant : Dub attend les montants en centimes pour les devises à deux décimales (par exemple, $10.00 correspond à
1000) et sous forme d’entier complet pour les devises sans décimales, telles que JPY. - Devise : utilisez les codes de devise ISO 4217, tels que USD, EUR et GBP. Dub convertit chaque vente en USD au dernier taux de change disponible.
- Essais gratuits : l’API Track Sale de Dub accepte un
amountde0, et les exemples n’ignorent pas les paiements de $0 ; chaque paiement de $0 est donc transmis à Dub comme une vente. Pour ignorer les paiements de $0, définissezwebhook.cancel = truelorsquetotal_amountest0. - Remboursements : si vous avez besoin d’un reporting précis du chiffre d’affaires, suivez les remboursements séparément.
Résolution des problèmes
Sales Not Appearing in Dub
Sales Not Appearing in Dub
- Vérifiez que votre clé API Dub est correcte et possède le scope
conversions.write. - Vérifiez que le
dub_click_idest capturé et enregistré dans les métadonnées du paiement. - Vérifiez que la transformation du webhook formate correctement le payload.
- Vérifiez que l’endpoint est abonné à
payment.succeeded. - Confirmez que le suivi des conversions est activé pour vos liens Dub.
- Ouvrez les tentatives de livraison de l’endpoint dans l’onglet Logs de Developer → Webhooks pour voir la réponse de Dub. Un paiement sans identifiant de clic est annulé et apparaît comme réussi.
Revenue Attribution Not Working
Revenue Attribution Not Working
- Confirmez que les clients cliquent sur vos liens courts Dub avant le paiement.
- Vérifiez que le cookie
dub_idest défini sur votre domaine. - Vérifiez que l’identifiant de clic dans les métadonnées du paiement correspond au clic effectué par le client.
- Capturez l’identifiant de clic avant de créer le paiement.
Transformation Errors
Transformation Errors
- Vérifiez que le payload correspond au format de l’API Track Sale de Dub.
- Vérifiez que les champs obligatoires,
customerExternalIdetamount, sont présents et queclickIdest défini pour l’attribution. - Vérifiez que le montant est un entier exprimé dans la plus petite unité monétaire, et non un nombre décimal.
- Vérifiez que l’URL de l’endpoint est
https://api.dub.co/track/sale. - Testez la transformation avec des payloads de webhook d’exemple.
Duplicate Sales Being Tracked
Duplicate Sales Being Tracked
- Suivez les ventes uniquement lors des événements
payment.succeeded, et non lors des événementspayment.processing. - Utilisez un
invoiceIdunique pour chaque vente. Dub n’enregistre qu’une seule vente pour chaqueinvoiceId. - Pour les renouvellements, construisez
invoiceIdà partir de l’ID de l’abonnement et de la période de facturation, comme indiqué dans Suivi des ventes par abonnement. Une valeur qui change à chaque livraison, telle que l’heure actuelle, enregistre une vente en double lorsqu’une livraison est réessayée.
Ressources supplémentaires
Dub Conversions Documentation
Découvrez les fonctionnalités de suivi des conversions et d’analyse de Dub.
Dub Track Sale API
Consultez la référence complète de l’API pour l’endpoint Track Sale de Dub.
Dub Dashboard
Consultez les analyses de conversion et les données d’attribution dans votre tableau de bord Dub.
Webhook Events Guide
Parcourez tous les événements de webhook Dodo Payments.
Pour obtenir de l’aide concernant cette intégration, contactez le support Dodo Payments à l’adresse support@dodopayments.com.