DataFast

Introdução

DataFast é uma ferramenta de análise focada em receita que mostra quais canais de marketing trazem clientes pagantes. Quando você envia suas transações do Dodo Payments para o DataFast, ele atribui a receita à fonte de tráfego original de cada cliente, permitindo ver quais canais e segmentos de clientes geram mais receita.

Esta integração requer sua chave de API do DataFast, que você cria no seu painel do DataFast.

Como Funciona

O DataFast identifica cada visitante com um ID armazenado no cookie datafast_visitor_id. Para atribuir a receita aos canais de marketing:

Capture o ID do visitante do DataFast no cookie datafast_visitor_id ao criar o checkout.
Armazene o ID do visitante no metadata do pagamento.
Envie o pagamento ao DataFast por meio da Payment API quando o pagamento for concluído.

O DataFast associa cada pagamento bem-sucedido à fonte de tráfego original do visitante, atribuindo a receita a esse canal.

Começando

Install DataFast Script

Instale o script de rastreamento do DataFast no seu site. O script define o cookie datafast_visitor_id que identifica cada visitante.Para obter instruções de instalação para sua plataforma, consulte a documentação do DataFast.

Get Your API Key

No seu painel do DataFast, abra as configurações do seu site, acesse API e clique em Create API Key.

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

Capture Visitor ID in Checkout

Ao criar um checkout, leia o ID do visitante do DataFast no cookie e adicione-o ao metadata do pagamento. Consulte a Etapa 1.

Send Payment Data via Webhook

Crie um endpoint de webhook que envie cada pagamento bem-sucedido à Payment API do DataFast. Consulte a Etapa 2.

Done

A receita aparece no seu painel do DataFast, atribuída ao canal de marketing que trouxe cada cliente.

Guia de implementação

Etapa 1: adicionar o ID do visitante aos metadados do checkout

Ao criar um checkout, leia o ID do visitante do DataFast no cookie e inclua-o no metadata do pagamento.

Os exemplos abaixo usam INLINE_CODE_PLACEHOLDER_387c606e6218259f8_END, que está obsoleto. Ele continua funcionando para integrações existentes, mas novas integrações devem usar Checkout Sessions (POST /checkouts), que aceitam metadata da mesma forma.

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

Etapa 2: enviar dados de pagamento ao DataFast

Crie um endpoint de webhook que envie pagamentos bem-sucedidos à Payment API do DataFast.

Open the Webhook Section

No dashboard do Dodo Payments, acesse Developer → Webhooks e clique em Add endpoint.

Caixa de diálogo Add endpoint com DataFast selecionado no menu suspenso Integration

Select DataFast

Em Integration, selecione DataFast.

Enter API Key

Em API key, cole sua chave de API do DataFast. O Dodo Payments a envia no cabeçalho Authorization de cada entrega.

URL do endpoint do DataFast preenchida e campo da chave de API

Check the URL and Events

Se Endpoint URL estiver vazio, insira https://datafa.st/api/v1/payments. Em Subscribed events, selecione payment.succeeded.

Configure Transformation

Em Transformation code, edite o handler para formatar os dados de pagamento para a Payment API do DataFast. Comece pelos exemplos.

Test & Create

Em Test this code, clique em Simulate para executar o handler com um payload de exemplo. Em seguida, clique em Create endpoint.

Exemplos de código de transformação

Cada handler é executado em payment.succeeded. Quando o metadata do pagamento não tem um ID de visitante, ele define webhook.cancel = true, portanto nenhuma solicitação é enviada ao DataFast. Uma entrega cancelada ainda aparece como bem-sucedida nos logs do webhook. A Payment API do DataFast recebe amount em unidades monetárias principais, por exemplo, 29.99. O Dodo Payments envia total_amount na menor unidade monetária, por exemplo, centavos para USD, portanto os exemplos fazem a conversão.

Atribuição básica de pagamentos

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

Como lidar com moedas sem casas decimais

Moedas sem casas decimais, como JPY, não têm unidade menor, portanto total_amount já está em unidades principais. Moedas com três casas decimais, como KWD, têm 1.000 unidades menores por unidade principal. Este exemplo converte o valor para cada caso, usando as moedas que o Dodo Payments trata como sem casas decimais e com três casas decimais:

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

Pagamentos de assinatura

Pagamentos de assinatura também acionam payment.succeeded, com subscription_id definido. Este handler envia todos os pagamentos de assinatura ao DataFast e define renewal: true nas renovações, para que o DataFast possa distinguir uma renovação do primeiro pagamento. Uma renovação é cobrada off-session, portanto seu payload tem subscription_id definido e checkout_session_id definido como null. O primeiro pagamento de uma assinatura criada por meio de uma Checkout Session tem checkout_session_id definido. Os pagamentos de renovação incluem o metadata da assinatura, portanto mantenha datafast_visitor_id nos metadados da assinatura para atribuir as renovações.

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

Práticas recomendadas

Capture o ID de visitante antecipadamente: armazene o ID de visitante do DataFast o mais cedo possível no seu fluxo de checkout, para que a atribuição permaneça precisa mesmo que o cliente saia e retorne mais tarde.

Inclua o ID de visitante nos metadados: sem o ID de visitante, o DataFast não consegue atribuir a receita aos canais de marketing.
Lide com moedas sem casas decimais: algumas moedas, como JPY e KRW, não têm casas decimais. Ajuste a conversão do valor para elas e para moedas com três casas decimais, como KWD.
Teste com pagamentos de exemplo: execute o handler usando Test this code e confirme se a integração funciona antes de entrar em produção.
Monitore seu dashboard do DataFast: verifique se os pagamentos aparecem com a atribuição esperada.
Conte com as novas tentativas do webhook: o DataFast ignora um pagamento cujo transaction_id já tenha sido registrado, portanto uma entrega repetida não cria uma duplicata.

Solução de problemas

Payments Not Appearing in DataFast

Verifique se sua chave de API do DataFast está correta e ativa.
Verifique se o datafast_visitor_id foi capturado e armazenado nos metadados do pagamento.
Verifique se a transformação do webhook formata o payload corretamente.
Verifique se o endpoint está inscrito em payment.succeeded.
Consulte o dashboard do DataFast em busca de mensagens de erro ou logs da API.
Abra as tentativas de entrega do endpoint na aba Logs de Developer → Webhooks para ver a resposta do DataFast. Um pagamento sem ID de visitante é cancelado e aparece como bem-sucedido.

Revenue Attribution Not Working

Confirme se o script de rastreamento do DataFast está instalado e em execução no seu site.
Verifique se o cookie datafast_visitor_id está definido.
Verifique se o ID de visitante nos metadados do pagamento corresponde ao ID registrado pelo DataFast para a visita.
Capture o ID de visitante antes de criar o checkout.
Consulte a documentação da Payment API do DataFast para obter mais orientações.

Transformation Errors

Verifique se o payload corresponde ao formato da Payment API do DataFast.
Verifique se todos os campos obrigatórios estão presentes: amount, currency e transaction_id. Inclua datafast_visitor_id para atribuição.
Verifique a conversão do valor: divida por 100 para a maioria das moedas, por 1.000 para moedas com três casas decimais e não divida para moedas sem casas decimais.
Verifique se a URL do endpoint é https://datafa.st/api/v1/payments.
Teste a transformação com payloads de webhook de exemplo.

Currency Conversion Issues

Para moedas sem casas decimais (BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF e XPF), envie o valor como está.
Para moedas com três casas decimais (BHD, IQD, JOD, KWD, LYD, OMR e TND), divida o valor por 1.000.
Para todas as outras moedas, divida o valor por 100 para converter da menor unidade para a unidade principal.
Verifique se o código da moeda usa o formato ISO 4217, por exemplo, USD, EUR ou JPY.

Recursos adicionais

DataFast Documentation

Saiba mais sobre a Payment API do DataFast e a atribuição de receita.

DataFast Dashboard

Visualize análises de receita e dados de atribuição no seu dashboard do DataFast.

Para obter ajuda com essa integração, entre em contato com o suporte do Dodo Payments pelo endereço support@dodopayments.com.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introdução

Como Funciona

Começando

Guia de implementação

Etapa 1: adicionar o ID do visitante aos metadados do checkout

Etapa 2: enviar dados de pagamento ao DataFast

Exemplos de código de transformação

Atribuição básica de pagamentos

Como lidar com moedas sem casas decimais

Pagamentos de assinatura

Práticas recomendadas

Solução de problemas

Recursos adicionais

DataFast Documentation

DataFast Dashboard

​Introdução

​Como Funciona

​Começando

​Guia de implementação

​Etapa 1: adicionar o ID do visitante aos metadados do checkout

​Etapa 2: enviar dados de pagamento ao DataFast

​Exemplos de código de transformação

​Atribuição básica de pagamentos

​Como lidar com moedas sem casas decimais

​Pagamentos de assinatura

​Práticas recomendadas

​Solução de problemas

​Recursos adicionais

DataFast Documentation

DataFast Dashboard

Introdução

Como Funciona

Começando

Guia de implementação

Etapa 1: adicionar o ID do visitante aos metadados do checkout

Etapa 2: enviar dados de pagamento ao DataFast

Exemplos de código de transformação

Atribuição básica de pagamentos

Como lidar com moedas sem casas decimais

Pagamentos de assinatura

Práticas recomendadas

Solução de problemas

Recursos adicionais