DataFast

Introduzione

DataFast è uno strumento di analisi incentrato sui ricavi che mostra quali canali di marketing portano clienti paganti. Quando invii le transazioni di Dodo Payments a DataFast, attribuisce i ricavi alla fonte di traffico originale di ogni cliente, così puoi vedere quali canali e segmenti di clientela generano più ricavi.

Questa integrazione richiede la tua chiave API di DataFast, che puoi creare nella tua dashboard di DataFast.

Come Funziona

DataFast identifica ogni visitatore tramite un ID memorizzato nel cookie datafast_visitor_id. Per attribuire i ricavi ai canali di marketing:

Acquisisci l’ID del visitatore di DataFast dal cookie datafast_visitor_id quando crei il checkout.
Memorizza l’ID del visitatore nel campo metadata del pagamento.
Invia il pagamento a DataFast tramite la sua Payment API quando il pagamento va a buon fine.

DataFast associa ogni pagamento completato alla fonte di traffico originale del visitatore, attribuendo così i ricavi a quel canale.

Iniziare

Install DataFast Script

Installa lo script di tracciamento di DataFast sul tuo sito web. Lo script imposta il cookie datafast_visitor_id che identifica ogni visitatore.Per le istruzioni di installazione relative alla tua piattaforma, consulta la documentazione di DataFast.

Get Your API Key

Nella tua dashboard di DataFast, apri le impostazioni del tuo sito web, vai su API e fai clic su Create API Key.

Mantieni sicura la tua chiave API. Non esporla mai nel codice lato client.

Capture Visitor ID in Checkout

Quando crei un checkout, leggi l’ID del visitatore di DataFast dal cookie e aggiungilo al campo metadata del pagamento. Consulta il Passaggio 1.

Send Payment Data via Webhook

Crea un endpoint webhook che invii ogni pagamento completato alla Payment API di DataFast. Consulta il Passaggio 2.

Done

I ricavi vengono visualizzati nella tua dashboard di DataFast, attribuiti al canale di marketing che ha portato ciascun cliente.

Guida all’implementazione

Passaggio 1: aggiungi l’ID del visitatore ai metadati del checkout

Quando crei un checkout, leggi l’ID del visitatore di DataFast dal cookie e includilo nel campo metadata del pagamento.

Gli esempi seguenti utilizzano POST /payments, che è deprecato. Continua a funzionare per le integrazioni esistenti, ma per le nuove integrazioni dovresti utilizzare Checkout Sessions (POST /checkouts), che accettano metadata allo stesso modo.

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
  },
});

Passaggio 2: invia i dati del pagamento a DataFast

Crea un endpoint webhook che invii i pagamenti completati alla Payment API di DataFast.

Open the Webhook Section

Nel dashboard di Dodo Payments, vai a Developer → Webhooks e fai clic su Add endpoint.

Finestra di dialogo Add endpoint con DataFast selezionato nel menu a discesa Integration

Select DataFast

In Integration, seleziona DataFast.

Enter API Key

In API key, incolla la tua chiave API di DataFast. Dodo Payments la invia nell’header Authorization di ogni consegna.

URL dell'endpoint DataFast compilato e campo della chiave API

Check the URL and Events

Se Endpoint URL è vuoto, inserisci https://datafa.st/api/v1/payments. In Subscribed events, seleziona payment.succeeded.

Configure Transformation

In Transformation code, modifica l’handler per formattare i dati di pagamento per la Payment API di DataFast. Inizia dagli esempi.

Test & Create

In Test this code, fai clic su Simulate per eseguire l’handler su un payload di esempio. Quindi fai clic su Create endpoint.

Esempi di transformation code

Ogni handler viene eseguito su payment.succeeded. Quando il campo metadata del pagamento non contiene un ID visitatore, imposta webhook.cancel = true, quindi nessuna richiesta viene inviata a DataFast. Una consegna annullata viene comunque mostrata come riuscita nei log del webhook. La Payment API di DataFast accetta amount nelle unità principali della valuta, ad esempio 29.99. Dodo Payments invia total_amount nell’unità più piccola della valuta, ad esempio i centesimi per USD, quindi gli esempi lo convertono.

Attribuzione di base dei pagamenti

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;
}

Gestione delle valute senza decimali

Le valute senza decimali, come JPY, non hanno un’unità minore, quindi total_amount è già espresso nelle unità principali. Le valute con tre decimali, come KWD, hanno 1.000 unità minori per ogni unità principale. Questo esempio converte l’importo per ciascun caso, utilizzando le valute che Dodo Payments tratta come valute senza decimali e con tre decimali:

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;
}

Pagamenti degli abbonamenti

Anche i pagamenti degli abbonamenti attivano payment.succeeded, con subscription_id impostato. Questo handler invia ogni pagamento dell’abbonamento a DataFast e imposta renewal: true sui rinnovi, così DataFast può distinguere un rinnovo dal primo pagamento. Un rinnovo viene addebitato off-session, quindi il relativo payload ha subscription_id impostato e checkout_session_id impostato su null. Il primo pagamento di un abbonamento creato tramite una Checkout Session ha checkout_session_id impostato. I pagamenti di rinnovo includono metadata dell’abbonamento, quindi mantieni datafast_visitor_id nei metadata dell’abbonamento per attribuire i rinnovi.

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;
}

Best practice

Acquisisci presto l’ID visitatore: salva l’ID visitatore di DataFast il prima possibile nel flusso di checkout, così l’attribuzione rimane accurata anche se il cliente abbandona il sito e torna in un secondo momento.

Includi l’ID visitatore nei metadata: senza l’ID visitatore, DataFast non può attribuire i ricavi ai canali di marketing.
Gestisci le valute senza decimali: alcune valute, come JPY e KRW, non hanno posizioni decimali. Adatta la conversione dell’importo per queste valute e per quelle con tre decimali, come KWD.
Esegui test con pagamenti di esempio: esegui l’handler con Test this code e verifica che l’integrazione funzioni prima di andare in produzione.
Monitora il dashboard di DataFast: verifica che i pagamenti vengano visualizzati con l’attribuzione prevista.
Affidati ai tentativi automatici del webhook: DataFast ignora un pagamento il cui transaction_id è già stato registrato, quindi una consegna ritentata non crea un duplicato.

Risoluzione dei problemi

Payments Not Appearing in DataFast

Verifica che la chiave API di DataFast sia corretta e attiva.
Controlla che datafast_visitor_id sia acquisito e salvato nei metadata del pagamento.
Controlla che la transformation del webhook formatti correttamente il payload.
Verifica che l’endpoint sia sottoscritto a payment.succeeded.
Controlla il dashboard di DataFast per individuare messaggi di errore o log API.
Apri i tentativi di consegna dell’endpoint nella scheda Logs di Developer → Webhooks per visualizzare la risposta di DataFast. Un pagamento senza ID visitatore viene annullato e visualizzato come riuscito.

Revenue Attribution Not Working

Conferma che lo script di tracciamento di DataFast sia installato e in esecuzione sul tuo sito web.
Verifica che il cookie datafast_visitor_id sia impostato.
Controlla che l’ID visitatore nei metadata del pagamento corrisponda a quello registrato da DataFast per la visita.
Acquisisci l’ID visitatore prima di creare il checkout.
Consulta la documentazione della Payment API di DataFast per ulteriori indicazioni.

Transformation Errors

Controlla che il payload corrisponda al formato della Payment API di DataFast.
Controlla che siano presenti tutti i campi obbligatori: amount, currency e transaction_id. Includi datafast_visitor_id per l’attribuzione.
Controlla la conversione dell’importo: dividi per 100 per la maggior parte delle valute, per 1.000 per le valute con tre decimali e non dividere per le valute senza decimali.
Verifica che l’URL dell’endpoint sia https://datafa.st/api/v1/payments.
Testa la transformation con payload di esempio del webhook.

Currency Conversion Issues

Per le valute senza decimali (BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF e XPF), invia l’importo così com’è.
Per le valute con tre decimali (BHD, IQD, JOD, KWD, LYD, OMR e TND), dividi l’importo per 1.000.
Per tutte le altre valute, dividi l’importo per 100 per convertirlo dall’unità più piccola all’unità principale.
Verifica che il codice valuta utilizzi il formato ISO 4217, ad esempio USD, EUR o JPY.

Risorse aggiuntive

DataFast Documentation

Scopri di più sulla Payment API di DataFast e sull’attribuzione dei ricavi.

DataFast Dashboard

Visualizza le analisi dei ricavi e i dati di attribuzione nel tuo dashboard di DataFast.

Per assistenza con questa integrazione, contatta il supporto di Dodo Payments all’indirizzo support@dodopayments.com.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introduzione

Come Funziona

Iniziare

Guida all’implementazione

Passaggio 1: aggiungi l’ID del visitatore ai metadati del checkout

Passaggio 2: invia i dati del pagamento a DataFast

Esempi di transformation code

Attribuzione di base dei pagamenti

Gestione delle valute senza decimali

Pagamenti degli abbonamenti

Best practice

Risoluzione dei problemi

Risorse aggiuntive

DataFast Documentation

DataFast Dashboard

​Introduzione

​Come Funziona

​Iniziare

​Guida all’implementazione

​Passaggio 1: aggiungi l’ID del visitatore ai metadati del checkout

​Passaggio 2: invia i dati del pagamento a DataFast

​Esempi di transformation code

​Attribuzione di base dei pagamenti

​Gestione delle valute senza decimali

​Pagamenti degli abbonamenti

​Best practice

​Risoluzione dei problemi

​Risorse aggiuntive

DataFast Documentation

DataFast Dashboard

Introduzione

Come Funziona

Iniziare

Guida all’implementazione

Passaggio 1: aggiungi l’ID del visitatore ai metadati del checkout

Passaggio 2: invia i dati del pagamento a DataFast

Esempi di transformation code

Attribuzione di base dei pagamenti

Gestione delle valute senza decimali

Pagamenti degli abbonamenti

Best practice

Risoluzione dei problemi

Risorse aggiuntive