Skip to main content

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.
Intégration d’un programme d’affiliation : cette intégration fonctionne également avec Dub Partners, le produit de programme d’affiliation de Dub. Dub attribue les ventes aux liens d’affiliation de vos partenaires, afin que vous puissiez suivre les recommandations, les commissions et les performances de chaque partenaire. Pour configurer un programme d’affiliation, consultez le guide de la fonctionnalité Affiliates.

How It Works

Lorsqu’un visiteur clique sur l’un de vos liens courts Dub, Dub enregistre un identifiant de clic unique dans le cookie dub_id. Pour attribuer les ventes à vos liens :
  1. Capturez l’identifiant de clic de Dub depuis le cookie dub_id lors de la création du checkout.
  2. Stockez l’identifiant de clic dans le metadata du paiement, avec l’identifiant de votre client dans votre système (l’identifiant externe).
  3. Envoyez la vente à Dub via son Track API lorsque le paiement réussit.
Dub associe chaque vente réussie au clic initial sur le lien, ce qui attribue la conversion à ce lien.

Prerequisites

Avant de configurer cette intégration, vous devez disposer des éléments suivants :
  1. Un compte Dub avec un espace de travail.
  2. Le suivi des conversions activé pour vos liens.
  3. 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.
Gardez votre clé API en lieu sûr. Ne l’exposez jamais dans du code côté client.
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 le metadata 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.
Boîte de dialogue Add endpoint avec Dub.co sélectionné dans la liste déroulante Integration
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.
Champ API key pour l'intégration Dub
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 lorsque metadata 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 handlers payment.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 indicateur is_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 webhook payment.succeeded. Le code utilise votre clé API Dub ; exécutez-le donc sur votre serveur, jamais dans le navigateur.

Bonnes pratiques

Capturez rapidement l’identifiant de clic : enregistrez l’identifiant de clic Dub le plus tôt possible dans votre parcours de paiement afin que l’attribution reste exacte, même si le client quitte votre site puis revient plus tard.
  • 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 customerExternalId pour obtenir des analyses précises au niveau du client.
  • Gérez le trafic organique : définissez webhook.cancel = true lorsqu’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 amount de 0, 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éfinissez webhook.cancel = true lorsque total_amount est 0.
  • 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

  • Vérifiez que votre clé API Dub est correcte et possède le scope conversions.write.
  • Vérifiez que le dub_click_id est 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.
  • Confirmez que les clients cliquent sur vos liens courts Dub avant le paiement.
  • Vérifiez que le cookie dub_id est 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.
  • Vérifiez que le payload correspond au format de l’API Track Sale de Dub.
  • Vérifiez que les champs obligatoires, customerExternalId et amount, sont présents et que clickId est 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.
  • Suivez les ventes uniquement lors des événements payment.succeeded, et non lors des événements payment.processing.
  • Utilisez un invoiceId unique pour chaque vente. Dub n’enregistre qu’une seule vente pour chaque invoiceId.
  • 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.
Dernière modification le 26 septembre 2026