DataFast

소개

DataFast는 결제 고객을 유입하는 마케팅 채널을 보여주는 수익 중심 analytics 도구입니다. Dodo Payments 거래를 DataFast로 전송하면 각 고객의 최초 트래픽 소스에 수익을 귀속하므로, 어떤 채널과 고객 세그먼트가 가장 많은 수익을 창출하는지 확인할 수 있습니다.

이 통합에는 DataFast dashboard에서 생성하는 DataFast API key가 필요합니다.

작동 방식

DataFast는 datafast_visitor_id cookie에 저장된 ID로 각 방문자를 식별합니다. 수익을 마케팅 채널에 귀속하려면 다음 단계를 따르세요.

DataFast visitor ID 캡처: checkout을 생성할 때 datafast_visitor_id cookie에서 visitor ID를 가져옵니다.
visitor ID 저장: payment의 metadata에 visitor ID를 저장합니다.
payment를 DataFast로 전송: payment가 성공하면 Payment API를 통해 DataFast로 전송합니다.

DataFast는 각 성공한 payment를 방문자의 최초 트래픽 소스와 매칭하여 수익을 해당 채널에 귀속합니다.

시작하기

Install DataFast Script

웹사이트에 DataFast tracking script를 설치합니다. 이 script는 각 방문자를 식별하는 datafast_visitor_id cookie를 설정합니다.플랫폼별 설치 방법은 DataFast documentation을 참조하세요.

Get Your API Key

DataFast dashboard에서 웹사이트 설정을 열고 API로 이동한 다음 Create API Key를 클릭합니다.

API key를 안전하게 보관하세요. client-side code에 절대 노출하지 마세요.

Capture Visitor ID in Checkout

checkout을 생성할 때 cookie에서 DataFast visitor ID를 읽고 payment의 metadata에 추가합니다. Step 1을 참조하세요.

Send Payment Data via Webhook

각 성공한 payment를 DataFast의 Payment API로 전송하는 webhook endpoint를 생성합니다. Step 2를 참조하세요.

Done

수익은 각 고객을 유입한 마케팅 채널에 귀속되어 DataFast dashboard에 표시됩니다.

구현 가이드

Step 1: Checkout Metadata에 Visitor ID 추가

checkout을 생성할 때 cookie에서 DataFast visitor ID를 읽고 payment의 metadata에 포함합니다.

아래 예제는 deprecated 상태인 POST /payments을 사용합니다. 기존 통합에서는 계속 작동하지만, 새 통합에서는 metadata을 동일한 방식으로 허용하는 Checkout Sessions(POST /checkouts)을 사용해야 합니다.

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

Step 2: Payment Data를 DataFast로 전송

성공한 payment를 DataFast의 Payment API로 전송하는 webhook endpoint를 생성합니다.

Open the Webhook Section

Dodo Payments 대시보드에서 Developer → Webhooks로 이동한 다음 Add endpoint를 클릭합니다.

Integration 드롭다운에서 DataFast가 선택된 Add endpoint 대화상자

Select DataFast

Integration에서 DataFast를 선택합니다.

Enter API Key

API key에 DataFast API key를 붙여 넣습니다. Dodo Payments는 모든 delivery의 Authorization 헤더에 이 값을 전송합니다.

DataFast endpoint URL과 API key 필드가 입력된 상태

Check the URL and Events

Endpoint URL이 비어 있으면 https://datafa.st/api/v1/payments을 입력합니다. Subscribed events에서 payment.succeeded을 선택합니다.

Configure Transformation

Transformation code에서 handler를 편집하여 DataFast의 Payment API에 맞는 형식으로 payment data를 변환합니다. 예시를 참고하여 시작할 수 있습니다.

Test & Create

Test this code에서 Simulate를 클릭하여 sample payload에 대해 handler를 실행합니다. 그런 다음 Create endpoint를 클릭합니다.

Transformation Code 예시

각 handler는 payment.succeeded에서 실행됩니다. payment의 metadata에 visitor ID가 없으면 webhook.cancel = true을 설정하므로 DataFast로 request가 전송되지 않습니다. 취소된 delivery도 webhook logs에서는 successful로 표시됩니다. DataFast의 Payment API는 amount을 major currency unit으로 받습니다. 예를 들어 29.99과 같습니다. Dodo Payments는 total_amount을 smallest currency unit으로 전송합니다. 예를 들어 USD의 cents가 이에 해당하므로, 아래 예시에서는 이를 변환합니다.

기본 Payment Attribution

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 currency에는 minor unit이 없으므로 total_amount은 이미 major unit으로 표시됩니다. KWD와 같은 three-decimal currency에는 major unit당 1,000개의 minor unit이 있습니다. 이 예시에서는 Dodo Payments가 zero-decimal 및 three-decimal로 처리하는 통화를 사용하여 각 경우의 amount를 변환합니다.

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도 payment.succeeded을 발생시키며, subscription_id이 설정됩니다. 이 handler는 모든 subscription payment를 DataFast로 전송하고 renewal 시 renewal: true을 설정하므로, DataFast에서 renewal과 첫 payment를 구분할 수 있습니다. Renewal은 off-session으로 청구되므로 payload에는 subscription_id이 설정되고 checkout_session_id은 null으로 설정됩니다. Checkout Session을 통해 생성된 subscription의 첫 payment에는 checkout_session_id이 설정됩니다. Renewal payment에는 subscription의 metadata이 포함되므로, renewal을 attribution하려면 subscription의 metadata에 datafast_visitor_id을 유지합니다.

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

모범 사례

visitor ID를 조기에 수집: checkout flow에서 DataFast visitor ID를 가능한 한 일찍 저장하여 customer가 나갔다가 나중에 돌아오더라도 attribution이 정확하게 유지되도록 합니다.

metadata에 visitor ID 포함: visitor ID가 없으면 DataFast에서 revenue를 marketing channel에 attribution할 수 없습니다.
zero-decimal currency 처리: JPY 및 KRW와 같은 일부 통화에는 decimal place가 없습니다. 이러한 통화와 KWD와 같은 three-decimal currency에 맞게 amount conversion을 조정합니다.
sample payment으로 테스트: Test this code를 사용하여 handler를 실행하고, live 환경으로 전환하기 전에 integration이 작동하는지 확인합니다.
DataFast dashboard 모니터링: payment가 예상한 attribution과 함께 표시되는지 확인합니다.
webhook retry 활용: DataFast는 이미 기록한 transaction_id이 있는 payment를 건너뛰므로, retry된 delivery가 duplicate를 생성하지 않습니다.

문제 해결

Payments Not Appearing in DataFast

DataFast API key가 올바르고 active 상태인지 확인합니다.
datafast_visitor_id이 수집되어 payment metadata에 저장되었는지 확인합니다.
webhook transformation이 payload를 올바르게 format하는지 확인합니다.
endpoint가 payment.succeeded을 구독하는지 확인합니다.
DataFast dashboard에서 error message 또는 API logs를 확인합니다.
DataFast의 response를 확인하려면 Developer → Webhooks의 Logs 탭에서 endpoint의 delivery attempts를 엽니다. visitor ID가 없는 payment는 취소되며 successful로 표시됩니다.

Revenue Attribution Not Working

DataFast tracking script가 website에 설치되어 실행 중인지 확인합니다.
datafast_visitor_id cookie가 설정되었는지 확인합니다.
payment metadata의 visitor ID가 DataFast가 visit에 대해 기록한 값과 일치하는지 확인합니다.
checkout을 생성하기 전에 visitor ID를 수집합니다.
자세한 내용은 DataFast의 Payment API documentation을 참조합니다.

Transformation Errors

payload가 DataFast의 Payment API format과 일치하는지 확인합니다.
필수 field가 모두 있는지 확인합니다: amount, currency, transaction_id. attribution을 위해 datafast_visitor_id을 포함합니다.
amount conversion을 확인합니다. 대부분의 통화는 100으로 나누고, three-decimal currency는 1,000으로 나누며, zero-decimal currency는 나누지 않습니다.
endpoint URL이 https://datafa.st/api/v1/payments인지 확인합니다.
sample webhook payload로 transformation을 테스트합니다.

Currency Conversion Issues

zero-decimal currency(BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF 및 XPF)는 amount를 그대로 전송합니다.
three-decimal currency(BHD, IQD, JOD, KWD, LYD, OMR 및 TND)는 amount를 1,000으로 나눕니다.
그 외 모든 통화는 smallest unit에서 major unit으로 변환하기 위해 amount를 100으로 나눕니다.
currency code가 ISO 4217 format을 사용하는지 확인합니다. 예를 들어 USD, EUR 또는 JPY과 같습니다.

추가 리소스

DataFast Documentation

DataFast의 Payment API와 revenue attribution에 대해 알아봅니다.

DataFast Dashboard

DataFast dashboard에서 revenue analytics 및 attribution data를 확인합니다.

이 integration에 대한 도움이 필요하면 support@dodopayments.com으로 Dodo Payments support에 문의하세요.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

소개

작동 방식

시작하기

구현 가이드

Step 1: Checkout Metadata에 Visitor ID 추가

Step 2: Payment Data를 DataFast로 전송

Transformation Code 예시

기본 Payment Attribution

소수점이 없는 통화 처리

Subscription Payments

모범 사례

문제 해결

추가 리소스

DataFast Documentation

DataFast Dashboard

​소개

​작동 방식

​시작하기

​구현 가이드

​Step 1: Checkout Metadata에 Visitor ID 추가

​Step 2: Payment Data를 DataFast로 전송

​Transformation Code 예시

​기본 Payment Attribution

​소수점이 없는 통화 처리

​Subscription Payments

​모범 사례

​문제 해결

​추가 리소스

DataFast Documentation

DataFast Dashboard

소개

작동 방식

시작하기

구현 가이드

Step 1: Checkout Metadata에 Visitor ID 추가

Step 2: Payment Data를 DataFast로 전송

Transformation Code 예시

기본 Payment Attribution

소수점이 없는 통화 처리

Subscription Payments

모범 사례

문제 해결

추가 리소스