DataFast

Giới thiệu

DataFast là công cụ phân tích ưu tiên doanh thu, cho biết những kênh marketing nào mang lại khách hàng trả phí. Khi bạn gửi các giao dịch Dodo Payments đến DataFast, công cụ này sẽ phân bổ doanh thu cho nguồn lưu lượng ban đầu của từng khách hàng, giúp bạn biết những kênh và phân khúc khách hàng nào tạo ra nhiều doanh thu nhất.

Tích hợp này yêu cầu API key DataFast của bạn, được tạo trong dashboard DataFast.

Cách hoạt động

DataFast nhận diện từng visitor bằng một ID được lưu trong cookie datafast_visitor_id. Để phân bổ doanh thu cho các kênh marketing:

Lấy visitor ID của DataFast từ cookie datafast_visitor_id khi bạn tạo checkout.
Lưu visitor ID vào metadata của payment.
Gửi payment đến DataFast thông qua Payment API khi payment thành công.

DataFast đối chiếu mỗi payment thành công với nguồn lưu lượng ban đầu của visitor, từ đó phân bổ doanh thu cho kênh tương ứng.

Bắt đầu

Install DataFast Script

Cài đặt tracking script của DataFast trên website của bạn. Script này thiết lập cookie datafast_visitor_id để nhận diện từng visitor.Để xem hướng dẫn cài đặt cho nền tảng của bạn, hãy xem tài liệu DataFast.

Get Your API Key

Trong dashboard DataFast, mở phần cài đặt website, đi đến API và nhấp Create API Key.

Bảo mật API key của bạn. Không bao giờ để lộ key trong client-side code.

Capture Visitor ID in Checkout

Khi tạo checkout, đọc visitor ID của DataFast từ cookie và thêm ID đó vào metadata của payment. Xem Bước 1.

Send Payment Data via Webhook

Tạo webhook endpoint để gửi từng payment thành công đến Payment API của DataFast. Xem Bước 2.

Done

Doanh thu sẽ xuất hiện trong dashboard DataFast của bạn và được phân bổ cho kênh marketing đã mang đến từng khách hàng.

Hướng dẫn triển khai

Bước 1: Thêm Visitor ID vào Checkout Metadata

Khi tạo checkout, đọc visitor ID của DataFast từ cookie và thêm ID đó vào metadata của payment.

Các ví dụ bên dưới sử dụng POST /payments, hiện đã deprecated. Tính năng này vẫn hoạt động với các tích hợp hiện có, nhưng các tích hợp mới nên sử dụng Checkout Sessions (POST /checkouts), vốn tiếp nhận metadata theo cùng cách.

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

Bước 2: Gửi Payment Data đến DataFast

Tạo webhook endpoint để gửi các payment thành công đến Payment API của DataFast.

Open the Webhook Section

Trong dashboard Dodo Payments, đi đến Developer → Webhooks và nhấp vào Add endpoint.

Hộp thoại Add endpoint với DataFast được chọn trong dropdown Integration

Select DataFast

Trong Integration, chọn DataFast.

Enter API Key

Trong API key, dán API key DataFast của bạn. Dodo Payments gửi key này trong header Authorization của mọi lần delivery.

URL endpoint của DataFast đã được điền và trường API key

Check the URL and Events

Nếu Endpoint URL đang trống, hãy nhập https://datafa.st/api/v1/payments. Trong Subscribed events, chọn payment.succeeded.

Configure Transformation

Trong Transformation code, chỉnh sửa handler để định dạng dữ liệu payment cho Payment API của DataFast. Bắt đầu từ các ví dụ.

Test & Create

Trong Test this code, nhấp vào Simulate để chạy handler với payload mẫu. Sau đó nhấp vào Create endpoint.

Ví dụ về Transformation Code

Mỗi handler chạy trên payment.succeeded. Khi metadata của payment không có visitor ID, handler đặt webhook.cancel = true, vì vậy không có request nào được gửi đến DataFast. Một delivery bị hủy vẫn hiển thị là thành công trong webhook logs. Payment API của DataFast nhận amount theo đơn vị tiền tệ chính, chẳng hạn 29.99. Dodo Payments gửi total_amount theo đơn vị tiền tệ nhỏ nhất, chẳng hạn cents đối với USD, nên các ví dụ sẽ chuyển đổi giá trị này.

Gán thuộc tính Payment cơ bản

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

Xử lý các loại tiền tệ không có chữ số thập phân

Các loại tiền tệ không có chữ số thập phân, chẳng hạn JPY, không có minor unit, vì vậy total_amount đã ở đơn vị chính. Các loại tiền tệ có ba chữ số thập phân, chẳng hạn KWD, có 1.000 minor unit trên mỗi đơn vị chính. Ví dụ này chuyển đổi amount cho từng trường hợp, sử dụng các loại tiền tệ mà Dodo Payments xử lý là không có chữ số thập phân và có ba chữ số thập phân:

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

Subscription Payments

Subscription payments cũng kích hoạt payment.succeeded, với subscription_id được thiết lập. Handler này gửi mọi subscription payment đến DataFast và thiết lập renewal: true cho các lần renewal, để DataFast có thể phân biệt renewal với payment đầu tiên. Một renewal được charge off-session, vì vậy payload của nó có subscription_id được thiết lập và checkout_session_id được đặt thành null. Payment đầu tiên của subscription được tạo thông qua Checkout Session có checkout_session_id được thiết lập. Renewal payments mang metadata của subscription, vì vậy hãy giữ datafast_visitor_id trong metadata của subscription để gán thuộc tính cho các renewal.

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

Phương pháp hay nhất

Capture visitor ID sớm: Lưu visitor ID của DataFast sớm nhất có thể trong quy trình checkout để attribution vẫn chính xác ngay cả khi customer rời đi và quay lại sau đó.

Đưa visitor ID vào metadata: Nếu không có visitor ID, DataFast không thể gán revenue cho các marketing channel.
Xử lý các loại tiền tệ không có chữ số thập phân: Một số loại tiền tệ, chẳng hạn JPY và KRW, không có chữ số thập phân. Điều chỉnh việc chuyển đổi amount cho các loại tiền này và cho các loại tiền tệ có ba chữ số thập phân như KWD.
Kiểm tra bằng payment mẫu: Chạy handler với Test this code và xác nhận integration hoạt động trước khi go live.
Theo dõi dashboard DataFast: Kiểm tra để đảm bảo các payment xuất hiện với attribution như mong đợi.
Dựa vào webhook retries: DataFast bỏ qua payment có transaction_id mà hệ thống đã ghi nhận, vì vậy delivery được retry không tạo bản trùng lặp.

Khắc phục sự cố

Payments Not Appearing in DataFast

Xác minh API key DataFast của bạn chính xác và đang hoạt động.
Kiểm tra để đảm bảo datafast_visitor_id được capture và lưu trong metadata của payment.
Kiểm tra để đảm bảo webhook transformation định dạng payload chính xác.
Xác minh endpoint đã subscribe vào payment.succeeded.
Kiểm tra dashboard DataFast để tìm error message hoặc API logs.
Mở các delivery attempts của endpoint trong tab Logs của Developer → Webhooks để xem response của DataFast. Payment không có visitor ID sẽ bị hủy và hiển thị là thành công.

Revenue Attribution Not Working

Xác nhận tracking script của DataFast đã được cài đặt và đang chạy trên website.
Xác minh cookie datafast_visitor_id đã được thiết lập.
Kiểm tra visitor ID trong metadata của payment có khớp với visitor ID DataFast đã ghi nhận cho lượt truy cập hay không.
Capture visitor ID trước khi tạo checkout.
Xem tài liệu Payment API của DataFast để biết thêm hướng dẫn.

Transformation Errors

Kiểm tra payload có khớp với format Payment API của DataFast hay không.
Kiểm tra tất cả required fields đã có mặt: amount, currency và transaction_id. Đưa datafast_visitor_id vào để attribution.
Kiểm tra việc chuyển đổi amount: chia cho 100 đối với hầu hết các loại tiền tệ, chia cho 1.000 đối với các loại tiền tệ có ba chữ số thập phân và không chia đối với các loại tiền tệ không có chữ số thập phân.
Xác minh URL endpoint là https://datafa.st/api/v1/payments.
Kiểm tra transformation bằng các webhook payload mẫu.

Currency Conversion Issues

Đối với các loại tiền tệ không có chữ số thập phân (BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF và XPF), gửi amount không thay đổi.
Đối với các loại tiền tệ có ba chữ số thập phân (BHD, IQD, JOD, KWD, LYD, OMR và TND), chia amount cho 1.000.
Đối với tất cả các loại tiền tệ khác, chia amount cho 100 để chuyển đổi từ đơn vị nhỏ nhất sang đơn vị chính.
Kiểm tra mã tiền tệ sử dụng format ISO 4217, chẳng hạn USD, EUR hoặc JPY.

Tài nguyên bổ sung

DataFast Documentation

Tìm hiểu về Payment API và revenue attribution của DataFast.

DataFast Dashboard

Xem revenue analytics và attribution data trong dashboard DataFast của bạn.

Để được hỗ trợ về integration này, hãy liên hệ bộ phận hỗ trợ Dodo Payments tại support@dodopayments.com.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Giới thiệu

Cách hoạt động

Bắt đầu

Hướng dẫn triển khai

Bước 1: Thêm Visitor ID vào Checkout Metadata

Bước 2: Gửi Payment Data đến DataFast

Ví dụ về Transformation Code

Gán thuộc tính Payment cơ bản

Xử lý các loại tiền tệ không có chữ số thập phân

Subscription Payments

Phương pháp hay nhất

Khắc phục sự cố

Tài nguyên bổ sung

DataFast Documentation

DataFast Dashboard

​Giới thiệu

​Cách hoạt động

​Bắt đầu

​Hướng dẫn triển khai

​Bước 1: Thêm Visitor ID vào Checkout Metadata

​Bước 2: Gửi Payment Data đến DataFast

​Ví dụ về Transformation Code

​Gán thuộc tính Payment cơ bản

​Xử lý các loại tiền tệ không có chữ số thập phân

​Subscription Payments

​Phương pháp hay nhất

​Khắc phục sự cố

​Tài nguyên bổ sung

DataFast Documentation

DataFast Dashboard

Giới thiệu

Cách hoạt động

Bắt đầu

Hướng dẫn triển khai

Bước 1: Thêm Visitor ID vào Checkout Metadata

Bước 2: Gửi Payment Data đến DataFast

Ví dụ về Transformation Code

Gán thuộc tính Payment cơ bản

Xử lý các loại tiền tệ không có chữ số thập phân

Subscription Payments

Phương pháp hay nhất

Khắc phục sự cố

Tài nguyên bổ sung