跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

​
介绍

DataFast 是一款以收入为导向的分析工具，帮助您发现哪些营销渠道驱动付费客户。通过将 Dodo Payments 与 DataFast 集成，您可以将收入归因于您的流量来源，识别高价值客户群体，并做出数据驱动的决策以推动业务增长。
此集成需要您的 DataFast API 密钥，您可以从您的 DataFast dashboard 获取。

​
工作原理

DataFast 通过存储在 cookie 中的唯一访客 ID 跟踪访问者。要将收入归因于营销渠道，您需要：
  1. 在创建结账会话时从 datafast_visitor_id cookie 捕获 DataFast 的访客 ID
  2. 将访客 ID 存储在您的支付元数据中
  3. 在支付成功时通过其 Payment API 向 DataFast 发送支付数据
这使 DataFast 能够将成功的支付与原始流量来源匹配，从而为您提供完整的收入归因。

​
开始使用

1

Install DataFast Script

首先，在您的网站上安装 DataFast 跟踪脚本。此脚本会创建用于跟踪访客的 datafast_visitor_id cookie。请访问 DataFast documentation 获取针对您所用平台的安装说明。
2

Get Your API Key

登录您的 DataFast dashboard，并进入网站设置以获取您的 API 密钥。
保持您的 API 密钥安全，切勿在客户端代码中暴露。
3

Capture Visitor ID in Checkout

在创建结账会话时，从 cookie 捕获 DataFast 访客 ID 并将其添加到您的支付元数据中。
4

Send Payment Data via Webhook

配置一个 webhook，在支付成功时将支付数据发送到 DataFast 的 Payment API。
5

Done!

🎉 现在收入数据将出现在您的 DataFast 仪表板中，并可完整归因到营销渠道。

​
实施指南

​
第 1 步：将访客 ID 添加到结账元数据

在创建结账会话时，从 cookie 中捕获 DataFast 访客 ID 并将其包含在您的支付元数据中。 
import { cookies } from 'next/headers';
import { dodopayments } from '@/lib/dodopayments';

export async function createCheckout(productId: string) {
  // Capture DataFast visitor ID from cookie
  const datafastVisitorId = cookies().get('datafast_visitor_id')?.value;

  const payment = await dodopayments.payments.create({
    product_id: productId,
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });

  return payment;
}

​
第 2 步：将支付数据发送到 DataFast

配置一个 webhook 端点，在支付成功时将支付数据发送到 DataFast 的支付 API。
1

Open the Webhook Section

在您的 Dodo Payments 仪表板中，导航至 Webhooks → + 添加端点 并展开集成下拉菜单。
添加端点和集成下拉菜单
2

Select DataFast

选择 DataFast 集成卡。
3

Enter API Key

在配置字段中提供您的 DataFast API 密钥。
添加 API 密钥
4

Configure Transformation

编辑转换代码，使其将支付数据格式化为 DataFast 的 Payment API 所需格式。
5

Test & Create

使用示例有效负载进行测试，然后点击 Create 以激活集成。

​
转换代码示例

​
基本支付归因

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

​
处理零小数货币

某些货币（如 JPY）不使用小数位。相应地调整金额计算：
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: JPY, KRW, CLP, etc.
      const zeroDecimalCurrencies = ['JPY', 'KRW', 'CLP', 'VND', 'UGX', 'MGA'];
      const isZeroDecimal = zeroDecimalCurrencies.includes(payment.currency);
      
      webhook.payload = {
        amount: isZeroDecimal 
          ? payment.total_amount // Use amount as-is for zero decimal currencies
          : payment.total_amount / 100, // Convert from cents for other currencies
        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;
}

​
订阅支付

对于定期订阅支付，您可以跟踪每笔支付：
subscription_payment.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Check if this is a subscription payment
    const isSubscription = payment.subscription_id !== null;
    
    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,
        // Optional: Add subscription context
        ...(isSubscription && {
          subscription_id: payment.subscription_id,
        }),
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
最佳实践

尽早捕获访客 ID：在结账流程中尽快存储 DataFast 访客 ID，以确保即使用户中途离开再返回也能正确归因。
  • 始终在元数据中包含访客 ID：没有访客 ID，DataFast 无法将收入归因于营销渠道
  • 处理零小数货币：某些货币（JPY、KRW 等）不使用小数位——相应地调整您的金额计算
  • 使用示例支付进行测试：在上线之前验证集成是否正常工作
  • 监控您的 DataFast 仪表板：检查支付是否正确显示并具有适当的归因
  • 使用 webhook 重试：DataFast 的支付 API 是幂等的，因此如果 webhook 失败，重试是安全的

​
故障排除

  • 验证您的 DataFast API 密钥是否正确且已激活
  • 检查 datafast_visitor_id 是否已被捕获并存储在支付元数据中
  • 确保 webhook 转换正在正确格式化有效负载
  • 验证 webhook 是否在 payment.succeeded 事件触发时运行
  • 在 DataFast 仪表板中查看是否有任何错误消息或 API 日志
  • 确认 DataFast 跟踪脚本已在您的网站上安装并正常运行
  • 验证 datafast_visitor_id cookie 是否已正确设置
  • 检查访客 ID 在创建结账和完成支付之间是否一致
  • 确保您在创建结账会话之前就已捕获访客 ID
  • 查阅 DataFast 的 Payment API documentation 以获得额外指导
  • 验证 JSON 结构是否与 DataFast 的 Payment API 格式匹配
  • 检查所有必填字段（amount、currency、transaction_id、datafast_visitor_id）是否存在
  • 确保金额已正确转换（对于大多数货币除以 100，零小数货币除外）
  • 验证 API 端点 URL 是否正确：https://datafa.st/api/v1/payments
  • 使用示例 webhook 有效负载测试转换
  • 对于零小数货币（JPY、KRW、CLP、VND、UGX、MGA），直接按原值发送金额，无需除以 100
  • 对于其他所有货币，需将金额除以 100 来从分转换为基础单位
  • 仔细核对货币代码是否符合 ISO 4217 格式（例如“USD”、“EUR”、“JPY”）

​
其他资源

DataFast Documentation

了解有关 DataFast 的 Payment API 和收入归因功能的更多信息。

DataFast Dashboard

访问您的 DataFast 仪表板，以查看收入分析和归因数据。
需要帮助吗？请联系 Dodo Payments 支持团队，发送邮件至 support@dodopayments.com 获取集成协助。
Last modified on April 20, 2026