DataFast

はじめに

DataFastは、支払いにつながった顧客をどのマーケティングチャネルが獲得したかを示す、収益重視の分析ツールです。Dodo Paymentsの取引をDataFastに送信すると、各顧客の最初のトラフィックソースに収益を帰属させるため、どのチャネルや顧客セグメントが最も多くの収益を生み出しているかを確認できます。

この連携にはDataFast API keyが必要です。API keyはDataFast dashboardで作成します。

仕組み

DataFastは、datafast_visitor_id cookieに保存されたIDで各訪問者を識別します。収益をマーケティングチャネルに帰属させるには、次の手順を実行します。

DataFastの訪問者IDを取得する: checkoutを作成するときに、datafast_visitor_id cookieから訪問者IDを取得します。
訪問者IDを保存する: 支払いのmetadataに訪問者IDを保存します。
支払いをDataFastに送信する: 支払いが成功したときに、Payment APIを通じて支払いをDataFastに送信します。

DataFastは、成功した各支払いを訪問者の最初のトラフィックソースと照合し、そのチャネルに収益を帰属させます。

始め方

Install DataFast Script

WebサイトにDataFast tracking scriptをインストールします。このscriptは、各訪問者を識別するdatafast_visitor_id cookieを設定します。ご利用のプラットフォームへのインストール手順については、DataFast documentationを参照してください。

Get Your API Key

DataFast dashboardでWebサイトの設定を開き、APIに移動してCreate API Keyをクリックします。

API keyは安全に管理してください。client-side codeで公開しないでください。

Capture Visitor ID in Checkout

checkoutを作成するときにcookieからDataFastの訪問者IDを読み取り、支払いのmetadataに追加します。Step 1を参照してください。

Send Payment Data via Webhook

成功した各支払いをDataFastのPayment APIに送信するwebhook endpointを作成します。Step 2を参照してください。

Done

収益はDataFast dashboardに表示され、各顧客を獲得したマーケティングチャネルに帰属します。

実装ガイド

Step 1: Checkout Metadataに訪問者IDを追加する

checkoutを作成するときにcookieからDataFastの訪問者IDを読み取り、支払いのmetadataに含めます。

以下の例ではPOST /paymentsを使用していますが、これはdeprecatedです。既存の連携では引き続き動作しますが、新しい連携ではCheckout Sessions（POST /checkouts）を使用してください。Checkout Sessionsは同じ方法でmetadataを受け取ります。

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: 支払いデータをDataFastに送信する

成功した支払いを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 はすべての配信の 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 で、DataFast の Payment API 用に決済データをフォーマットするようハンドラーを編集します。例を参考にしてください。

Test & Create

Test this code で Simulate をクリックし、サンプルペイロードに対してハンドラーを実行します。次に Create endpoint をクリックします。

Transformation Code の例

各ハンドラーは payment.succeeded 上で実行されます。決済の metadata に visitor ID がない場合は、webhook.cancel = true を設定するため、DataFast へのリクエストは送信されません。キャンセルされた配信も webhook logs では成功として表示されます。 DataFast の Payment API は、amount を主要通貨単位で受け取ります。たとえば 29.99 です。Dodo Payments は total_amount を最小通貨単位で送信します。たとえば USD のセント単位です。そのため、例ではこれを変換しています。

基本的な決済アトリビューション

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 などの小数点以下の桁がない通貨には、minor unit がありません。そのため、total_amount はすでに主要通貨単位になっています。KWD などの小数点以下3桁の通貨には、主要通貨単位あたり1,000の minor unit があります。この例では、Dodo Payments が小数点以下の桁がない通貨および小数点以下3桁の通貨として扱う通貨を使用し、それぞれのケースで金額を変換します。

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

サブスクリプション決済

サブスクリプション決済でも payment.succeeded が発生し、subscription_id が設定されます。このハンドラーはすべてのサブスクリプション決済を DataFast に送信し、更新時には renewal: true を設定します。これにより、DataFast は更新決済と初回決済を区別できます。更新決済は off-session で請求されるため、そのペイロードでは subscription_id が設定され、checkout_session_id は null に設定されます。Checkout Session を通じて作成されたサブスクリプションの初回決済では、checkout_session_id が設定されます。更新決済にはサブスクリプションの metadata が含まれるため、更新をアトリビューションできるよう、サブスクリプションの 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 を早い段階で取得する: チェックアウトフローのできるだけ早い段階で DataFast visitor ID を保存し、顧客が離脱して後から戻ってきた場合でもアトリビューションの精度を維持できるようにします。

visitor ID を metadata に含める: visitor ID がないと、DataFast はマーケティングチャネルに収益をアトリビューションできません。
小数点以下の桁がない通貨を処理する: JPY や KRW など、一部の通貨には小数点以下の桁がありません。また、KWD などの小数点以下3桁の通貨についても、金額変換を調整してください。
サンプル決済でテストする: Test this code でハンドラーを実行し、本番稼働前にインテグレーションが機能することを確認します。
DataFast ダッシュボードを監視する: 決済が想定どおりのアトリビューションで表示されることを確認します。
webhook の再試行を利用する: DataFast は、すでに記録した transaction_id を持つ決済をスキップするため、配信が再試行されても重複は作成されません。

トラブルシューティング

Payments Not Appearing in DataFast

DataFast API key が正しく、有効であることを確認します。
datafast_visitor_id が取得され、決済 metadata に保存されていることを確認します。
webhook transformation によってペイロードが正しくフォーマットされていることを確認します。
endpoint が payment.succeeded を購読していることを確認します。
DataFast ダッシュボードでエラーメッセージまたは API logs を確認します。
Developer → Webhooks の Logs タブで endpoint の配信試行を開き、DataFast のレスポンスを確認します。visitor ID のない決済はキャンセルされ、成功として表示されます。

Revenue Attribution Not Working

DataFast tracking script が Web サイトにインストールされ、実行されていることを確認します。
datafast_visitor_id cookie が設定されていることを確認します。
決済 metadata の visitor ID が、DataFast が訪問に対して記録したものと一致することを確認します。
checkout を作成する前に visitor ID を取得します。
詳細については、DataFast の Payment API documentation を参照してください。

Transformation Errors

ペイロードが DataFast の Payment API 形式に一致することを確認します。
必須フィールドがすべて存在することを確認します: amount、currency、transaction_id。アトリビューションには datafast_visitor_id を含めます。
金額変換を確認します: ほとんどの通貨では100で割り、小数点以下3桁の通貨では1,000で割り、小数点以下の桁がない通貨では割りません。
endpoint URL が https://datafa.st/api/v1/payments であることを確認します。
サンプル webhook ペイロードで transformation をテストします。

Currency Conversion Issues

小数点以下の桁がない通貨（BIF、CLP、DJF、GNF、JPY、KMF、KRW、MGA、PYG、RWF、UGX、VND、VUV、XAF、XOF、XPF）では、金額をそのまま送信します。
小数点以下3桁の通貨（BHD、IQD、JOD、KWD、LYD、OMR、TND）では、金額を1,000で割ります。
その他すべての通貨では、最小単位から主要単位に変換するため、金額を100で割ります。
通貨コードが ISO 4217 形式であることを確認します。たとえば USD、EUR、JPY です。

追加リソース

DataFast Documentation

DataFast の Payment API と収益アトリビューションについて説明します。

DataFast Dashboard

DataFast ダッシュボードで収益分析とアトリビューションデータを確認します。

このインテグレーションについてサポートが必要な場合は、support@dodopayments.com から Dodo Payments サポートにお問い合わせください。

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

はじめに

仕組み

始め方

実装ガイド

Step 1: Checkout Metadataに訪問者IDを追加する

Step 2: 支払いデータをDataFastに送信する

Transformation Code の例

基本的な決済アトリビューション

小数点以下の桁がない通貨の処理

サブスクリプション決済

ベストプラクティス

トラブルシューティング

追加リソース

DataFast Documentation

DataFast Dashboard

​はじめに

​仕組み

​始め方

​実装ガイド

​Step 1: Checkout Metadataに訪問者IDを追加する

​Step 2: 支払いデータをDataFastに送信する

​Transformation Code の例

​基本的な決済アトリビューション

​小数点以下の桁がない通貨の処理

​サブスクリプション決済

​ベストプラクティス

​トラブルシューティング

​追加リソース

DataFast Documentation

DataFast Dashboard

はじめに

仕組み

始め方

実装ガイド

Step 1: Checkout Metadataに訪問者IDを追加する

Step 2: 支払いデータをDataFastに送信する

Transformation Code の例

基本的な決済アトリビューション

小数点以下の桁がない通貨の処理

サブスクリプション決済

ベストプラクティス

トラブルシューティング

追加リソース