DataFast

Introduction

DataFast est un outil d’analyse axé sur les revenus qui indique quels canaux marketing génèrent des clients payants. Lorsque vous envoyez vos transactions Dodo Payments à DataFast, celui-ci attribue les revenus à la source de trafic d’origine de chaque client, afin que vous puissiez voir quels canaux et segments de clients génèrent le plus de revenus.

Cette intégration nécessite votre clé API DataFast, que vous créez dans votre tableau de bord DataFast.

Comment ça fonctionne

DataFast identifie chaque visiteur à l’aide d’un ID stocké dans le cookie datafast_visitor_id. Pour attribuer les revenus aux canaux marketing :

Capturez l’ID du visiteur DataFast depuis le cookie datafast_visitor_id lorsque vous créez le checkout.
Enregistrez l’ID du visiteur dans le metadata du paiement.
Envoyez le paiement à DataFast via son Payment API lorsque le paiement réussit.

DataFast associe chaque paiement réussi à la source de trafic d’origine du visiteur, ce qui attribue les revenus à ce canal.

Prise en main

Install DataFast Script

Installez le script de suivi DataFast sur votre site. Le script définit le cookie datafast_visitor_id qui identifie chaque visiteur.Pour obtenir les instructions d’installation correspondant à votre plateforme, consultez la documentation DataFast.

Get Your API Key

Dans votre tableau de bord DataFast, ouvrez les paramètres de votre site, accédez à API, puis cliquez sur Create API Key.

Conservez votre clé API en lieu sûr. Ne l’exposez jamais dans du code côté client.

Capture Visitor ID in Checkout

Lorsque vous créez un checkout, lisez l’ID du visiteur DataFast dans le cookie et ajoutez-le au metadata du paiement. Consultez l’étape 1.

Send Payment Data via Webhook

Créez un endpoint webhook qui envoie chaque paiement réussi au Payment API de DataFast. Consultez l’étape 2.

Done

Les revenus apparaissent dans votre tableau de bord DataFast, attribués au canal marketing qui a amené chaque client.

Guide d’implémentation

Étape 1 : ajouter l’ID du visiteur aux métadonnées du checkout

Lorsque vous créez un checkout, lisez l’ID du visiteur DataFast dans le cookie et incluez-le dans le metadata du paiement.

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.

import { cookies } from 'next/headers';
import { dodopayments } from '@/lib/dodopayments';

export async function createCheckout(productId: string) {
  // Capture DataFast visitor ID from cookie (cookies() is async in Next.js 15 and later)
  const datafastVisitorId = (await cookies()).get('datafast_visitor_id')?.value;

  const payment = await dodopayments.payments.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId ?? '', // Store visitor ID in metadata
    },
  });

  return payment;
}

const express = require('express');
const router = express.Router();

// dodopayments is your initialized Dodo Payments client
router.post('/create-checkout', async (req, res) => {
  // Capture DataFast visitor ID from cookie (req.cookies requires the cookie-parser middleware)
  const datafastVisitorId = req.cookies?.datafast_visitor_id;

  const payment = await dodopayments.payments.create({
    product_cart: [{ product_id: req.body.productId, quantity: 1 }],
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });

  res.json({ payment });
});

// Capture DataFast visitor ID from cookie
const datafastVisitorId = getCookie('datafast_visitor_id'); // Use your framework's cookie method

// dodopayments is your initialized Dodo Payments client, and productId is the product to sell
const payment = await dodopayments.payments.create({
  product_cart: [{ product_id: productId, quantity: 1 }],
  // ... other payment configuration
  metadata: {
    datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
  },
});

Étape 2 : envoyer les données de paiement à DataFast

Créez un endpoint webhook qui envoie les paiements réussis au Payment API de DataFast.

Open the Webhook Section

Dans le tableau de bord Dodo Payments, accédez à Developer → Webhooks et cliquez sur Add endpoint.

Boîte de dialogue d’ajout d’un endpoint avec DataFast sélectionné dans la liste déroulante Integration

Select DataFast

Dans Integration, sélectionnez DataFast.

Enter API Key

Dans API key, collez votre clé API DataFast. Dodo Payments l’envoie dans l’en-tête Authorization de chaque livraison.

URL de l’endpoint DataFast renseignée et champ de clé API

Check the URL and Events

Si Endpoint URL est vide, saisissez https://datafa.st/api/v1/payments. Dans Subscribed events, sélectionnez payment.succeeded.

Configure Transformation

Sous Transformation code, modifiez le gestionnaire pour formater les données de paiement pour la Payment API de DataFast. Commencez à partir des exemples.

Test & Create

Sous Test this code, cliquez sur Simulate pour exécuter le gestionnaire avec un exemple de payload. Cliquez ensuite sur Create endpoint.

Exemples de code de transformation

Chaque gestionnaire s’exécute sur payment.succeeded. Lorsque le metadata du paiement ne contient aucun ID de visiteur, il définit webhook.cancel = true afin qu’aucune requête ne soit envoyée à DataFast. Une livraison annulée apparaît tout de même comme réussie dans les journaux des webhooks. La Payment API de DataFast attend amount dans les unités monétaires principales, par exemple 29.99. Dodo Payments envoie total_amount dans la plus petite unité monétaire, par exemple en centimes pour l’USD ; les exemples effectuent donc la conversion.

Attribution de paiement de base

basic_payment.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Only send to DataFast if visitor ID exists in metadata
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100, // Convert from cents to dollars
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

Gérer les devises sans décimales

Les devises sans décimales, comme le JPY, n’ont pas d’unité mineure ; total_amount est donc déjà exprimé dans l’unité principale. Les devises à trois décimales, comme le KWD, comptent 1 000 unités mineures par unité principale. Cet exemple convertit le montant dans chaque cas, en utilisant les devises que Dodo Payments traite comme des devises sans décimales et à trois décimales :

zero_decimal.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      // Zero-decimal currencies: the smallest unit is the major unit
      const zeroDecimalCurrencies = ['BIF', 'CLP', 'DJF', 'GNF', 'JPY', 'KMF', 'KRW', 'MGA', 'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF'];
      // Three-decimal currencies: 1 major unit = 1000 minor units
      const threeDecimalCurrencies = ['BHD', 'IQD', 'JOD', 'KWD', 'LYD', 'OMR', 'TND'];
      const isZeroDecimal = zeroDecimalCurrencies.includes(payment.currency);
      const isThreeDecimal = threeDecimalCurrencies.includes(payment.currency);
      
      webhook.payload = {
        amount: isZeroDecimal 
          ? payment.total_amount // Use amount as-is for zero decimal currencies
          : payment.total_amount / (isThreeDecimal ? 1000 : 100), // Convert from minor units
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

Paiements d’abonnement

Les paiements d’abonnement déclenchent également payment.succeeded, avec subscription_id défini. Ce gestionnaire envoie chaque paiement d’abonnement à DataFast et définit renewal: true lors des renouvellements, afin que DataFast puisse distinguer un renouvellement du premier paiement. Un renouvellement est facturé hors session ; son payload contient donc subscription_id et checkout_session_id est défini sur null. Le premier paiement d’un abonnement créé via une Checkout Session contient checkout_session_id. Les paiements de renouvellement contiennent le metadata de l’abonnement ; conservez donc datafast_visitor_id dans les métadonnées de l’abonnement afin d’attribuer les renouvellements.

subscription_payment.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // A renewal belongs to a subscription and isn't paid through a checkout session
    const isRenewal = Boolean(payment.subscription_id) && !payment.checkout_session_id;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100,
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
        renewal: isRenewal,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

Bonnes pratiques

Capturer l’ID de visiteur rapidement : stockez l’ID de visiteur DataFast 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.

Inclure l’ID de visiteur dans les métadonnées : sans l’ID de visiteur, DataFast ne peut pas attribuer les revenus aux canaux marketing.
Gérer les devises sans décimales : certaines devises, comme le JPY et le KRW, n’ont aucune décimale. Adaptez leur conversion de montant, ainsi que celle des devises à trois décimales comme le KWD.
Tester avec des paiements d’exemple : exécutez le gestionnaire avec Test this code et confirmez que l’intégration fonctionne avant sa mise en production.
Surveiller votre tableau de bord DataFast : vérifiez que les paiements apparaissent avec l’attribution attendue.
S’appuyer sur les nouvelles tentatives des webhooks : DataFast ignore un paiement dont le transaction_id a déjà été enregistré ; une livraison réessayée ne crée donc pas de doublon.

Résolution des problèmes

Payments Not Appearing in DataFast

Vérifiez que votre clé API DataFast est correcte et active.
Vérifiez que le datafast_visitor_id est capturé et stocké 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.
Consultez le tableau de bord DataFast pour voir les messages d’erreur ou les journaux d’API.
Ouvrez les tentatives de livraison de l’endpoint dans l’onglet Logs de Developer → Webhooks pour voir la réponse de DataFast. Un paiement sans ID de visiteur est annulé et apparaît comme réussi.

Revenue Attribution Not Working

Confirmez que le script de suivi DataFast est installé et fonctionne sur votre site web.
Vérifiez que le cookie datafast_visitor_id est défini.
Vérifiez que l’ID de visiteur dans les métadonnées du paiement correspond à celui que DataFast a enregistré pour la visite.
Capturez l’ID de visiteur avant de créer le paiement.
Consultez la documentation de la Payment API de DataFast pour obtenir davantage de conseils.

Transformation Errors

Vérifiez que le payload correspond au format de la Payment API de DataFast.
Vérifiez que tous les champs requis sont présents : amount, currency et transaction_id. Incluez datafast_visitor_id pour l’attribution.
Vérifiez la conversion du montant : divisez par 100 pour la plupart des devises, par 1 000 pour les devises à trois décimales et ne divisez pas pour les devises sans décimales.
Vérifiez que l’URL de l’endpoint est https://datafa.st/api/v1/payments.
Testez la transformation avec des payloads de webhook d’exemple.

Currency Conversion Issues

Pour les devises sans décimales (BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF et XPF), envoyez le montant tel quel.
Pour les devises à trois décimales (BHD, IQD, JOD, KWD, LYD, OMR et TND), divisez le montant par 1 000.
Pour toutes les autres devises, divisez le montant par 100 pour le convertir de la plus petite unité vers l’unité principale.
Vérifiez que le code devise utilise le format ISO 4217, par exemple USD, EUR ou JPY.

Ressources supplémentaires

DataFast Documentation

Découvrez la Payment API de DataFast et l’attribution des revenus.

DataFast Dashboard

Consultez les analyses de revenus et les données d’attribution dans votre tableau de bord DataFast.

Pour obtenir de l’aide concernant cette intégration, contactez le support Dodo Payments à l’adresse support@dodopayments.com.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introduction

Comment ça fonctionne

Prise en main

Guide d’implémentation

Étape 1 : ajouter l’ID du visiteur aux métadonnées du checkout

Étape 2 : envoyer les données de paiement à DataFast

Exemples de code de transformation

Attribution de paiement de base

Gérer les devises sans décimales

Paiements d’abonnement

Bonnes pratiques

Résolution des problèmes

Ressources supplémentaires

DataFast Documentation

DataFast Dashboard

​Introduction

​Comment ça fonctionne

​Prise en main

​Guide d’implémentation

​Étape 1 : ajouter l’ID du visiteur aux métadonnées du checkout

​Étape 2 : envoyer les données de paiement à DataFast

​Exemples de code de transformation

​Attribution de paiement de base

​Gérer les devises sans décimales

​Paiements d’abonnement

​Bonnes pratiques

​Résolution des problèmes

​Ressources supplémentaires

DataFast Documentation

DataFast Dashboard

Introduction

Comment ça fonctionne

Prise en main

Guide d’implémentation

Étape 1 : ajouter l’ID du visiteur aux métadonnées du checkout

Étape 2 : envoyer les données de paiement à DataFast

Exemples de code de transformation

Attribution de paiement de base

Gérer les devises sans décimales

Paiements d’abonnement

Bonnes pratiques

Résolution des problèmes

Ressources supplémentaires