DataFast - Dodo Payments Documentation

Introdução

O DataFast é uma ferramenta de análise focada em receita que ajuda você a descobrir quais canais de marketing geram clientes pagantes. Ao integrar o Dodo Payments com o DataFast, você pode atribuir receita às suas fontes de tráfego, identificar segmentos de clientes de alto valor e tomar decisões baseadas em dados para crescer seu negócio.

Esta integração exige sua chave de API do DataFast, que você pode obter no seu painel do DataFast.

Como Funciona

O DataFast rastreia visitantes através de um ID de visitante único armazenado em um cookie. Para atribuir receita a canais de marketing, você precisa:

Capture o ID do visitante do DataFast do cookie datafast_visitor_id ao criar sessões de checkout
Armazene o ID do visitante nos metadados do pagamento
Envie os dados do pagamento ao DataFast quando os pagamentos forem bem-sucedidos usando a API de Pagamentos deles

Isso permite que o DataFast associe pagamentos bem-sucedidos à fonte de tráfego original, fornecendo a você uma atribuição de receita completa.

Começando

Install DataFast Script

Primeiro, instale o script de rastreamento do DataFast no seu site. Isso cria o cookie datafast_visitor_id que rastreia os visitantes.Consulte a documentação do DataFast para obter instruções de instalação específicas da sua plataforma.

Get Your API Key

Faça login no seu painel do DataFast e navegue até as configurações do seu site para obter sua chave de API.

Mantenha sua chave de API segura e nunca a exponha em código do lado do cliente.

Capture Visitor ID in Checkout

Ao criar uma sessão de checkout, capture o ID do visitante do DataFast do cookie e adicione-o aos metadados do pagamento.

Send Payment Data via Webhook

Configure um webhook para enviar dados de pagamento à API de Pagamentos do DataFast quando os pagamentos forem bem-sucedidos.

Done!

🎉 Os dados de receita agora aparecerão no seu painel do DataFast com atribuição completa aos canais de marketing.

Guia de Implementação

Passo 1: Adicionar ID do Visitante aos Metadados do Checkout

Ao criar uma sessão de checkout, capture o ID do visitante do DataFast do cookie e inclua-o em seus metadados de pagamento.

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_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();

router.post('/create-checkout', async (req, res) => {
  // Capture DataFast visitor ID from cookie
  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

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

Passo 2: Enviar Dados de Pagamento para o DataFast

Configure um endpoint de webhook para enviar dados de pagamento para a API de Pagamento do DataFast quando os pagamentos forem bem-sucedidos.

Open the Webhook Section

No seu painel do Dodo Payments, navegue até Webhooks → + Adicionar Endpoint e expanda o menu suspenso de integrações.

Adicionar Endpoint e menu suspenso de integrações

Select DataFast

Escolha o cartão de integração DataFast.

Enter API Key

Forneça sua chave API DataFast no campo de configuração.

Configure Transformation

Edite o código de transformação para formatar os dados de pagamento para a API de Pagamentos do DataFast.

Test & Create

Teste com cargas úteis de exemplo e clique em Create para ativar a integração.

Exemplos de Código de Transformação

Atribuição Básica de Pagamento

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

Lidar com Moedas sem Casas Decimais

Algumas moedas (como JPY) não usam casas decimais. Ajuste o cálculo do valor conforme necessário:

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

Pagamentos de Assinatura

Para pagamentos de assinatura recorrentes, você pode rastrear cada pagamento:

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

Melhores Práticas

Capture o ID do visitante cedo: Armazene o ID do visitante do DataFast o mais rápido possível no fluxo do checkout para garantir atribuição precisa, mesmo que o usuário saia e retorne depois.

Sempre inclua o ID do visitante nos metadados: Sem o ID do visitante, o DataFast não pode atribuir receita aos canais de marketing
Lide com moedas sem casas decimais: Algumas moedas (JPY, KRW, etc.) não usam casas decimais—ajuste seu cálculo de valor conforme necessário
Teste com pagamentos de exemplo: Verifique se a integração funciona corretamente antes de entrar em produção
Monitore seu painel do DataFast: Verifique se os pagamentos estão aparecendo corretamente com a atribuição adequada
Use tentativas de webhook: A API de Pagamento do DataFast é idempotente, então as tentativas são seguras se um webhook falhar

Solução de Problemas

Payments not appearing in DataFast

Verifique se sua chave de API do DataFast está correta e ativa
Confirme se o datafast_visitor_id está sendo capturado e armazenado nos metadados do pagamento
Garanta que a transformação do webhook esteja formatando corretamente a carga útil
Verifique se o webhook está sendo acionado nos eventos payment.succeeded
Confira o painel do DataFast para mensagens de erro ou logs da API

Revenue attribution not working

Confirme se o script de rastreamento do DataFast está instalado e funcionando no seu site
Verifique se o cookie datafast_visitor_id está sendo definido corretamente
Confira se os IDs dos visitantes batem entre a criação do checkout e a conclusão do pagamento
Certifique-se de capturar o ID do visitante antes de criar a sessão de checkout
Revise a documentação da API de Pagamentos do DataFast para obter orientações adicionais

Transformation errors

Valide se a estrutura JSON corresponde ao formato da API de Pagamentos do DataFast
Verifique se todos os campos obrigatórios (amount, currency, transaction_id, datafast_visitor_id) estão presentes
Certifique-se de que o valor está sendo convertido corretamente (divida por 100 na maioria das moedas, exceto moedas com zero casas decimais)
Verifique se a URL do endpoint da API está correta: https://datafa.st/api/v1/payments
Teste a transformação com cargas úteis de webhook de exemplo

Currency conversion issues

Para moedas com zero casas decimais (JPY, KRW, CLP, VND, UGX, MGA), envie o valor conforme recebido, sem dividir por 100
Para todas as outras moedas, divida o valor por 100 para converter de centavos para a unidade base
Confira se o código da moeda corresponde ao formato ISO 4217 (por exemplo, “USD”, “EUR”, “JPY”)

Recursos Adicionais

DataFast Documentation

Saiba mais sobre a API de Pagamentos do DataFast e os recursos de atribuição de receita.

DataFast Dashboard

Acesse seu painel do DataFast para visualizar análises de receita e dados de atribuição.

Precisa de ajuda? Entre em contato com o suporte do Dodo Payments em support@dodopayments.com para obter assistência com a integração.

​Introdução

​Como Funciona

​Começando

​Guia de Implementação

​Passo 1: Adicionar ID do Visitante aos Metadados do Checkout

​Passo 2: Enviar Dados de Pagamento para o DataFast

​Exemplos de Código de Transformação

​Atribuição Básica de Pagamento

​Lidar com Moedas sem Casas Decimais

​Pagamentos de Assinatura

​Melhores Práticas

​Solução de Problemas

​Recursos Adicionais

DataFast Documentation

DataFast Dashboard

Introdução

Como Funciona

Começando

Guia de Implementação

Passo 1: Adicionar ID do Visitante aos Metadados do Checkout

Passo 2: Enviar Dados de Pagamento para o DataFast

Exemplos de Código de Transformação

Atribuição Básica de Pagamento

Lidar com Moedas sem Casas Decimais

Pagamentos de Assinatura

Melhores Práticas

Solução de Problemas

Recursos Adicionais