DataFast

Pendahuluan

DataFast adalah alat analitik yang mengutamakan pendapatan dan menunjukkan kanal pemasaran mana yang mendatangkan pelanggan yang melakukan pembayaran. Saat Anda mengirim transaksi Dodo Payments ke DataFast, DataFast mengatribusikan pendapatan ke sumber traffic awal setiap pelanggan, sehingga Anda dapat melihat kanal dan segmen pelanggan mana yang menghasilkan pendapatan terbanyak.

Integrasi ini memerlukan API key DataFast, yang Anda buat di dasbor DataFast.

Cara Kerjanya

DataFast mengidentifikasi setiap pengunjung dengan ID yang disimpan di cookie datafast_visitor_id. Untuk mengatribusikan pendapatan ke kanal pemasaran:

Ambil visitor ID DataFast dari cookie datafast_visitor_id saat Anda membuat checkout.
Simpan visitor ID di metadata pembayaran.
Kirim pembayaran ke DataFast melalui Payment API-nya saat pembayaran berhasil.

DataFast mencocokkan setiap pembayaran yang berhasil dengan sumber traffic awal pengunjung, lalu mengatribusikan pendapatan ke kanal tersebut.

Memulai

Install DataFast Script

Instal skrip pelacakan DataFast di situs web Anda. Skrip tersebut menetapkan cookie datafast_visitor_id yang mengidentifikasi setiap pengunjung.Untuk petunjuk instalasi bagi platform Anda, lihat dokumentasi DataFast.

Get Your API Key

Di dasbor DataFast, buka pengaturan situs web Anda, buka API, lalu klik Create API Key.

Jaga keamanan API key Anda. Jangan pernah mengeksposnya di client-side code.

Capture Visitor ID in Checkout

Saat membuat checkout, baca visitor ID DataFast dari cookie dan tambahkan ke metadata pembayaran. Lihat Langkah 1.

Send Payment Data via Webhook

Buat endpoint webhook yang mengirim setiap pembayaran yang berhasil ke Payment API DataFast. Lihat Langkah 2.

Done

Pendapatan akan muncul di dasbor DataFast Anda, diatribusikan ke kanal pemasaran yang mendatangkan setiap pelanggan.

Panduan Implementasi

Langkah 1: Tambahkan Visitor ID ke Metadata Checkout

Saat membuat checkout, baca visitor ID DataFast dari cookie dan sertakan di metadata pembayaran.

Contoh di bawah menggunakan POST /payments, yang sudah deprecated. Fitur ini masih berfungsi untuk integrasi yang sudah ada, tetapi integrasi baru sebaiknya menggunakan Checkout Sessions (POST /checkouts), yang menerima metadata dengan cara yang sama.

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

Langkah 2: Kirim Data Pembayaran ke DataFast

Buat endpoint webhook yang mengirim pembayaran yang berhasil ke Payment API DataFast.

Open the Webhook Section

Di dashboard Dodo Payments, buka Developer → Webhooks lalu klik Add endpoint.

Add endpoint dialog with DataFast selected in the Integration dropdown

Select DataFast

Di Integration, pilih DataFast.

Enter API Key

Di API key, tempel API key DataFast Anda. Dodo Payments mengirimkannya di header Authorization pada setiap pengiriman.

DataFast endpoint URL filled in and the API key field

Check the URL and Events

Jika Endpoint URL kosong, masukkan https://datafa.st/api/v1/payments. Di Subscribed events, pilih payment.succeeded.

Configure Transformation

Di bagian Transformation code, edit handler untuk memformat data pembayaran untuk Payment API DataFast. Mulai dari contoh.

Test & Create

Di bagian Test this code, klik Simulate untuk menjalankan handler menggunakan payload sampel. Kemudian klik Create endpoint.

Contoh Kode Transformasi

Setiap handler berjalan pada payment.succeeded. Jika metadata pembayaran tidak memiliki ID pengunjung, handler menetapkan webhook.cancel = true, sehingga tidak ada permintaan yang dikirim ke DataFast. Pengiriman yang dibatalkan tetap ditampilkan sebagai berhasil di log webhook. Payment API DataFast menerima amount dalam satuan mata uang utama, misalnya 29.99. Dodo Payments mengirim total_amount dalam satuan mata uang terkecil, misalnya sen untuk USD, sehingga contoh-contoh tersebut mengonversinya.

Atribusi Pembayaran Dasar

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

Menangani Mata Uang Tanpa Desimal

Mata uang tanpa desimal, seperti JPY, tidak memiliki unit minor, sehingga total_amount sudah dalam satuan utama. Mata uang dengan tiga desimal, seperti KWD, memiliki 1.000 unit minor per unit utama. Contoh ini mengonversi jumlah untuk setiap kasus menggunakan mata uang yang diperlakukan Dodo Payments sebagai mata uang tanpa desimal dan tiga desimal:

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

Pembayaran Langganan

Pembayaran langganan juga memicu payment.succeeded, dengan subscription_id ditetapkan. Handler ini mengirim setiap pembayaran langganan ke DataFast dan menetapkan renewal: true pada perpanjangan, sehingga DataFast dapat membedakan perpanjangan dari pembayaran pertama. Perpanjangan ditagihkan secara off-session, sehingga payload-nya memiliki subscription_id dan checkout_session_id ditetapkan ke null. Pembayaran pertama langganan yang dibuat melalui Checkout Session memiliki checkout_session_id yang ditetapkan. Pembayaran perpanjangan membawa metadata langganan, jadi pertahankan datafast_visitor_id dalam metadata langganan untuk mengatribusikan perpanjangan.

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

Praktik Terbaik

Tangkap ID pengunjung lebih awal: Simpan ID pengunjung DataFast sedini mungkin dalam alur checkout Anda agar atribusi tetap akurat meskipun pelanggan pergi dan kembali nanti.

Sertakan ID pengunjung dalam metadata: Tanpa ID pengunjung, DataFast tidak dapat mengatribusikan pendapatan ke channel pemasaran.
Tangani mata uang tanpa desimal: Beberapa mata uang, seperti JPY dan KRW, tidak memiliki angka desimal. Sesuaikan konversi jumlah untuk mata uang tersebut dan untuk mata uang dengan tiga desimal seperti KWD.
Uji dengan pembayaran sampel: Jalankan handler menggunakan Test this code, lalu pastikan integrasi berfungsi sebelum Anda menggunakannya secara langsung.
Pantau dashboard DataFast Anda: Pastikan pembayaran muncul dengan atribusi yang diharapkan.
Andalkan percobaan ulang webhook: DataFast melewati pembayaran yang transaction_id-nya sudah direkam, sehingga pengiriman yang dicoba ulang tidak membuat duplikat.

Pemecahan Masalah

Payments Not Appearing in DataFast

Pastikan API key DataFast Anda benar dan aktif.
Pastikan datafast_visitor_id ditangkap dan disimpan dalam metadata pembayaran.
Pastikan transformasi webhook memformat payload dengan benar.
Pastikan endpoint berlangganan ke payment.succeeded.
Periksa dashboard DataFast untuk pesan error atau log API.
Buka percobaan pengiriman endpoint di tab Logs pada Developer → Webhooks untuk melihat respons DataFast. Pembayaran tanpa ID pengunjung dibatalkan dan ditampilkan sebagai berhasil.

Revenue Attribution Not Working

Pastikan script pelacakan DataFast terpasang dan berjalan di situs web Anda.
Pastikan cookie datafast_visitor_id telah ditetapkan.
Pastikan ID pengunjung dalam metadata pembayaran cocok dengan ID yang direkam DataFast untuk kunjungan tersebut.
Tangkap ID pengunjung sebelum membuat checkout.
Lihat dokumentasi Payment API DataFast untuk panduan lebih lanjut.

Transformation Errors

Pastikan payload sesuai dengan format Payment API DataFast.
Pastikan semua field wajib tersedia: amount, currency, dan transaction_id. Sertakan datafast_visitor_id untuk atribusi.
Periksa konversi jumlah: bagi dengan 100 untuk sebagian besar mata uang, dengan 1.000 untuk mata uang dengan tiga desimal, dan jangan membaginya untuk mata uang tanpa desimal.
Pastikan URL endpoint adalah https://datafa.st/api/v1/payments.
Uji transformasi dengan payload webhook sampel.

Currency Conversion Issues

Untuk mata uang tanpa desimal (BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF, dan XPF), kirim jumlah apa adanya.
Untuk mata uang dengan tiga desimal (BHD, IQD, JOD, KWD, LYD, OMR, dan TND), bagi jumlah dengan 1.000.
Untuk semua mata uang lainnya, bagi jumlah dengan 100 untuk mengonversinya dari unit terkecil ke unit utama.
Pastikan kode mata uang menggunakan format ISO 4217, misalnya USD, EUR, atau JPY.

Sumber Daya Tambahan

DataFast Documentation

Pelajari Payment API DataFast dan atribusi pendapatan.

DataFast Dashboard

Lihat analitik pendapatan dan data atribusi di dashboard DataFast Anda.

Untuk bantuan terkait integrasi ini, hubungi dukungan Dodo Payments di support@dodopayments.com.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Pendahuluan

Cara Kerjanya

Memulai

Panduan Implementasi

Langkah 1: Tambahkan Visitor ID ke Metadata Checkout

Langkah 2: Kirim Data Pembayaran ke DataFast

Contoh Kode Transformasi

Atribusi Pembayaran Dasar

Menangani Mata Uang Tanpa Desimal

Pembayaran Langganan

Praktik Terbaik

Pemecahan Masalah

Sumber Daya Tambahan

DataFast Documentation

DataFast Dashboard

​Pendahuluan

​Cara Kerjanya

​Memulai

​Panduan Implementasi

​Langkah 1: Tambahkan Visitor ID ke Metadata Checkout

​Langkah 2: Kirim Data Pembayaran ke DataFast

​Contoh Kode Transformasi

​Atribusi Pembayaran Dasar

​Menangani Mata Uang Tanpa Desimal

​Pembayaran Langganan

​Praktik Terbaik

​Pemecahan Masalah

​Sumber Daya Tambahan

DataFast Documentation

DataFast Dashboard

Pendahuluan

Cara Kerjanya

Memulai

Panduan Implementasi

Langkah 1: Tambahkan Visitor ID ke Metadata Checkout

Langkah 2: Kirim Data Pembayaran ke DataFast

Contoh Kode Transformasi

Atribusi Pembayaran Dasar

Menangani Mata Uang Tanpa Desimal

Pembayaran Langganan

Praktik Terbaik

Pemecahan Masalah

Sumber Daya Tambahan