DataFast

Einführung

DataFast ist ein Analytics-Tool mit Fokus auf Umsatz, das zeigt, welche Marketingkanäle zahlende Kunden bringen. Wenn Sie Ihre Dodo Payments-Transaktionen an DataFast senden, ordnet es den Umsatz der ursprünglichen Traffic-Quelle jedes Kunden zu. So sehen Sie, welche Kanäle und Kundensegmente den meisten Umsatz generieren.

Für diese Integration benötigen Sie Ihren DataFast API key, den Sie in Ihrem DataFast-Dashboard erstellen.

So funktioniert es

DataFast identifiziert jeden Besucher anhand einer ID, die im datafast_visitor_id-Cookie gespeichert wird. So ordnen Sie den Umsatz Marketingkanälen zu:

Erfassen Sie die DataFast-Besucher-ID aus dem datafast_visitor_id-Cookie, wenn Sie den Checkout erstellen.
Speichern Sie die Besucher-ID im metadata der Zahlung.
Senden Sie die Zahlung an DataFast über die Payment API, sobald die Zahlung erfolgreich ist.

DataFast ordnet jede erfolgreiche Zahlung der ursprünglichen Traffic-Quelle des Besuchers zu und weist den Umsatz dadurch diesem Kanal zu.

Erste Schritte

Install DataFast Script

Installieren Sie das DataFast-Tracking-Skript auf Ihrer Website. Das Skript setzt das datafast_visitor_id-Cookie, das jeden Besucher identifiziert.Anweisungen zur Installation für Ihre Plattform finden Sie in der DataFast-Dokumentation.

Get Your API Key

Öffnen Sie in Ihrem DataFast-Dashboard die Einstellungen Ihrer Website, gehen Sie zu API und klicken Sie auf Create API Key.

Bewahren Sie Ihren API key sicher auf. Legen Sie ihn niemals in clientseitigem Code offen.

Capture Visitor ID in Checkout

Wenn Sie einen Checkout erstellen, lesen Sie die DataFast-Besucher-ID aus dem Cookie und fügen Sie sie zum metadata der Zahlung hinzu. Siehe Schritt 1.

Send Payment Data via Webhook

Erstellen Sie einen Webhook-Endpunkt, der jede erfolgreiche Zahlung an die Payment API von DataFast sendet. Siehe Schritt 2.

Done

Der Umsatz wird in Ihrem DataFast-Dashboard angezeigt und dem Marketingkanal zugeordnet, über den der jeweilige Kunde gewonnen wurde.

Implementierungsleitfaden

Schritt 1: Besucher-ID zu den Checkout-Metadaten hinzufügen

Wenn Sie einen Checkout erstellen, lesen Sie die DataFast-Besucher-ID aus dem Cookie und fügen Sie sie zum metadata der Zahlung hinzu.

Die folgenden Beispiele verwenden POST /payments, das veraltet ist. Es funktioniert weiterhin für bestehende Integrationen, neue Integrationen sollten jedoch Checkout Sessions (POST /checkouts) verwenden, die metadata auf dieselbe Weise akzeptieren.

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

Schritt 2: Zahlungsdaten an DataFast senden

Erstellen Sie einen Webhook-Endpunkt, der erfolgreiche Zahlungen an die Payment API von DataFast sendet.

Open the Webhook Section

Gehen Sie im Dodo Payments-Dashboard zu Developer → Webhooks und klicken Sie auf Add endpoint.

Dialog zum Hinzufügen eines Endpunkts mit ausgewähltem DataFast im Dropdown Integration

Select DataFast

Wählen Sie unter Integration die Option DataFast aus.

Enter API Key

Fügen Sie unter API key Ihren DataFast-API-Schlüssel ein. Dodo Payments sendet ihn im Authorization-Header jeder Zustellung.

Ausgefüllte DataFast-Endpunkt-URL und API-Schlüsselfeld

Check the URL and Events

Wenn Endpoint URL leer ist, geben Sie https://datafa.st/api/v1/payments ein. Wählen Sie unter Subscribed events payment.succeeded aus.

Configure Transformation

Bearbeiten Sie unter Transformation code den Handler, um Zahlungsdaten für die Payment API von DataFast zu formatieren. Beginnen Sie mit den Beispielen.

Test & Create

Klicken Sie unter Test this code auf Simulate, um den Handler mit einer Beispiel-Payload auszuführen. Klicken Sie anschließend auf Create endpoint.

Beispiele für Transformationscode

Jeder Handler wird bei payment.succeeded ausgeführt. Wenn die metadata der Zahlung keine Besucher-ID enthält, setzt er webhook.cancel = true, sodass keine Anfrage an DataFast gesendet wird. Eine abgebrochene Zustellung wird in den Webhook-Protokollen weiterhin als erfolgreich angezeigt. Die Payment API von DataFast erwartet amount in den Haupteinheiten der Währung, zum Beispiel 29.99. Dodo Payments sendet total_amount in der kleinsten Währungseinheit, zum Beispiel Cent für USD. Daher rechnen die Beispiele diesen Wert um.

Grundlegende Zahlungszuordnung

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

Umgang mit Währungen ohne Dezimalstellen

Währungen ohne Dezimalstellen wie JPY haben keine Untereinheit, daher ist total_amount bereits in Haupteinheiten angegeben. Währungen mit drei Dezimalstellen wie KWD haben 1.000 Untereinheiten pro Haupteinheit. Dieses Beispiel rechnet den Betrag für jeden Fall um und verwendet dabei die Währungen, die Dodo Payments als Währungen ohne beziehungsweise mit drei Dezimalstellen behandelt:

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

Abonnementzahlungen

Auch Abonnementzahlungen lösen payment.succeeded aus, wobei subscription_id gesetzt ist. Dieser Handler sendet jede Abonnementzahlung an DataFast und setzt bei Verlängerungen renewal: true, damit DataFast eine Verlängerung von der ersten Zahlung unterscheiden kann. Eine Verlängerung wird off-session belastet. Daher ist subscription_id in der Payload gesetzt und checkout_session_id auf null gesetzt. Bei der ersten Zahlung eines Abonnements, das über eine Checkout Session erstellt wurde, ist checkout_session_id gesetzt. Verlängerungszahlungen enthalten die metadata des Abonnements. Speichern Sie daher datafast_visitor_id in den Metadaten des Abonnements, um Verlängerungen zuzuordnen.

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 Practices

Besucher-ID früh erfassen: Speichern Sie die DataFast-Besucher-ID so früh wie möglich in Ihrem Checkout-Ablauf, damit die Zuordnung korrekt bleibt, auch wenn der Kunde die Seite verlässt und später zurückkehrt.

Besucher-ID in Metadaten aufnehmen: Ohne die Besucher-ID kann DataFast Umsätze keinen Marketingkanälen zuordnen.
Währungen ohne Dezimalstellen behandeln: Einige Währungen wie JPY und KRW haben keine Dezimalstellen. Passen Sie die Betragsumrechnung für diese Währungen sowie für Währungen mit drei Dezimalstellen wie KWD an.
Mit Beispielzahlungen testen: Führen Sie den Handler mit Test this code aus und bestätigen Sie, dass die Integration funktioniert, bevor Sie live gehen.
Ihr DataFast-Dashboard überwachen: Prüfen Sie, ob Zahlungen mit der erwarteten Zuordnung angezeigt werden.
Webhook-Wiederholungen nutzen: DataFast überspringt eine Zahlung, deren transaction_id bereits erfasst wurde. Eine erneut zugestellte Zahlung erzeugt daher kein Duplikat.

Fehlerbehebung

Payments Not Appearing in DataFast

Überprüfen Sie, ob Ihr DataFast-API-Schlüssel korrekt und aktiv ist.
Prüfen Sie, ob datafast_visitor_id erfasst und in den Zahlungsmetadaten gespeichert wird.
Prüfen Sie, ob die Webhook-Transformation die Payload korrekt formatiert.
Überprüfen Sie, ob der Endpunkt payment.succeeded abonniert hat.
Prüfen Sie das DataFast-Dashboard auf Fehlermeldungen oder API-Protokolle.
Öffnen Sie die Zustellversuche des Endpunkts im Tab Logs unter Developer → Webhooks, um die Antwort von DataFast anzuzeigen. Eine Zahlung ohne Besucher-ID wird abgebrochen und als erfolgreich angezeigt.

Revenue Attribution Not Working

Bestätigen Sie, dass das DataFast-Tracking-Skript auf Ihrer Website installiert ist und ausgeführt wird.
Überprüfen Sie, ob das Cookie datafast_visitor_id gesetzt ist.
Prüfen Sie, ob die Besucher-ID in den Zahlungsmetadaten mit der von DataFast für den Besuch erfassten ID übereinstimmt.
Erfassen Sie die Besucher-ID, bevor Sie den Checkout erstellen.
Weitere Hinweise finden Sie in der Dokumentation der Payment API von DataFast.

Transformation Errors

Prüfen Sie, ob die Payload dem Format der Payment API von DataFast entspricht.
Prüfen Sie, ob alle erforderlichen Felder vorhanden sind: amount, currency und transaction_id. Nehmen Sie datafast_visitor_id für die Zuordnung auf.
Prüfen Sie die Betragsumrechnung: Teilen Sie bei den meisten Währungen durch 100, bei Währungen mit drei Dezimalstellen durch 1.000 und bei Währungen ohne Dezimalstellen gar nicht.
Überprüfen Sie, ob die Endpunkt-URL https://datafa.st/api/v1/payments lautet.
Testen Sie die Transformation mit Beispiel-Payloads von Webhooks.

Currency Conversion Issues

Senden Sie bei Währungen ohne Dezimalstellen (BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF und XPF) den Betrag unverändert.
Teilen Sie den Betrag bei Währungen mit drei Dezimalstellen (BHD, IQD, JOD, KWD, LYD, OMR und TND) durch 1.000.
Teilen Sie den Betrag bei allen anderen Währungen durch 100, um ihn von der kleinsten Einheit in die Haupteinheit umzurechnen.
Prüfen Sie, ob der Währungscode das ISO-4217-Format verwendet, zum Beispiel USD, EUR oder JPY.

Zusätzliche Ressourcen

DataFast Documentation

Lesen Sie mehr über die Payment API von DataFast und die Umsatzzuordnung.

DataFast Dashboard

Zeigen Sie Umsatzanalysen und Zuordnungsdaten in Ihrem DataFast-Dashboard an.

Wenn Sie Hilfe bei dieser Integration benötigen, wenden Sie sich unter support@dodopayments.com an den Support von Dodo Payments.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Einführung

So funktioniert es

Erste Schritte

Implementierungsleitfaden

Schritt 1: Besucher-ID zu den Checkout-Metadaten hinzufügen

Schritt 2: Zahlungsdaten an DataFast senden

Beispiele für Transformationscode

Grundlegende Zahlungszuordnung

Umgang mit Währungen ohne Dezimalstellen

Abonnementzahlungen

Best Practices

Fehlerbehebung

Zusätzliche Ressourcen

DataFast Documentation

DataFast Dashboard

​Einführung

​So funktioniert es

​Erste Schritte

​Implementierungsleitfaden

​Schritt 1: Besucher-ID zu den Checkout-Metadaten hinzufügen

​Schritt 2: Zahlungsdaten an DataFast senden

​Beispiele für Transformationscode

​Grundlegende Zahlungszuordnung

​Umgang mit Währungen ohne Dezimalstellen

​Abonnementzahlungen

​Best Practices

​Fehlerbehebung

​Zusätzliche Ressourcen

DataFast Documentation

DataFast Dashboard

Einführung

So funktioniert es

Erste Schritte

Implementierungsleitfaden

Schritt 1: Besucher-ID zu den Checkout-Metadaten hinzufügen

Schritt 2: Zahlungsdaten an DataFast senden

Beispiele für Transformationscode

Grundlegende Zahlungszuordnung

Umgang mit Währungen ohne Dezimalstellen

Abonnementzahlungen

Best Practices

Fehlerbehebung

Zusätzliche Ressourcen