DataFast

Introducción

DataFast es una herramienta de analíticas centrada en los ingresos que muestra qué canales de marketing atraen a clientes que pagan. Cuando envías tus transacciones de Dodo Payments a DataFast, atribuye los ingresos a la fuente de tráfico original de cada cliente, para que puedas ver qué canales y segmentos de clientes generan más ingresos.

Esta integración requiere tu clave de API de DataFast, que puedes crear en tu panel de DataFast.

Cómo Funciona

DataFast identifica a cada visitante con un ID almacenado en la cookie datafast_visitor_id. Para atribuir los ingresos a los canales de marketing:

Captura el ID del visitante de DataFast desde la cookie datafast_visitor_id cuando crees el checkout.
Almacena el ID del visitante en el metadata del pago.
Envía el pago a DataFast mediante su Payment API cuando el pago se complete correctamente.

DataFast relaciona cada pago completado correctamente con la fuente de tráfico original del visitante y atribuye los ingresos a ese canal.

Comenzando

Install DataFast Script

Instala el script de seguimiento de DataFast en tu sitio web. El script establece la cookie datafast_visitor_id que identifica a cada visitante.Para consultar las instrucciones de instalación para tu plataforma, visita la documentación de DataFast.

Get Your API Key

En tu panel de DataFast, abre la configuración de tu sitio web, ve a API y haz clic en Create API Key.

Mantén tu clave de API segura. Nunca la expongas en código del lado del cliente.

Capture Visitor ID in Checkout

Cuando crees un checkout, lee el ID del visitante de DataFast desde la cookie y añádelo al metadata del pago. Consulta el Paso 1.

Send Payment Data via Webhook

Crea un endpoint de webhook que envíe cada pago completado correctamente a la Payment API de DataFast. Consulta el Paso 2.

Done

Los ingresos aparecen en tu panel de DataFast, atribuidos al canal de marketing que atrajo a cada cliente.

Guía de implementación

Paso 1: Añadir el ID del visitante a los metadatos del checkout

Cuando crees un checkout, lee el ID del visitante de DataFast desde la cookie e inclúyelo en el metadata del pago.

Los ejemplos siguientes utilizan POST /payments, que está deprecated. Sigue funcionando para las integraciones existentes, pero las integraciones nuevas deben usar Checkout Sessions (POST /checkouts), que aceptan metadata de la misma manera.

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

Paso 2: Enviar los datos del pago a DataFast

Crea un endpoint de webhook que envíe los pagos completados correctamente a la Payment API de DataFast.

Open the Webhook Section

En el panel de Dodo Payments, ve a Developer → Webhooks y haz clic en Add endpoint.

Diálogo para añadir un endpoint con DataFast seleccionado en el menú desplegable de Integration

Select DataFast

En Integration, selecciona DataFast.

Enter API Key

En API key, pega tu clave de API de DataFast. Dodo Payments la envía en el encabezado Authorization de cada entrega.

URL del endpoint de DataFast completada y campo de clave de API

Check the URL and Events

Si Endpoint URL está vacío, introduce https://datafa.st/api/v1/payments. En Subscribed events, selecciona payment.succeeded.

Configure Transformation

En Transformation code, edita el handler para dar formato a los datos de pago para la Payment API de DataFast. Empieza con los ejemplos.

Test & Create

En Test this code, haz clic en Simulate para ejecutar el handler con un payload de ejemplo. Después, haz clic en Create endpoint.

Ejemplos de código de transformación

Cada handler se ejecuta en payment.succeeded. Cuando el metadata del pago no tiene un ID de visitante, establece webhook.cancel = true, por lo que no se envía ninguna solicitud a DataFast. Una entrega cancelada sigue apareciendo como correcta en los registros del webhook. La Payment API de DataFast recibe amount en unidades monetarias principales, por ejemplo, 29.99. Dodo Payments envía total_amount en la unidad monetaria más pequeña, por ejemplo, centavos para USD, por lo que los ejemplos realizan la conversión.

Atribución básica de pagos

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

Gestión de monedas sin decimales

Las monedas sin decimales, como JPY, no tienen una unidad menor, por lo que total_amount ya está expresado en unidades principales. Las monedas con tres decimales, como KWD, tienen 1.000 unidades menores por cada unidad principal. Este ejemplo convierte el importe para cada caso, utilizando las monedas que Dodo Payments trata como monedas sin decimales y con tres decimales:

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

Pagos de suscripciones

Los pagos de suscripciones también activan payment.succeeded, con subscription_id establecido. Este handler envía cada pago de suscripción a DataFast y establece renewal: true en las renovaciones, para que DataFast pueda distinguir una renovación del primer pago. Una renovación se cobra fuera de sesión, por lo que su payload tiene subscription_id establecido y checkout_session_id establecido en null. El primer pago de una suscripción creada mediante una Checkout Session tiene checkout_session_id establecido. Los pagos de renovación incluyen el metadata de la suscripción, así que conserva datafast_visitor_id en los metadatos de la suscripción para atribuir las renovaciones.

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ácticas recomendadas

Captura pronto el ID de visitante: Guarda el ID de visitante de DataFast lo antes posible en el flujo de checkout, para que la atribución siga siendo precisa aunque el cliente se vaya y vuelva más tarde.

Incluye el ID de visitante en los metadatos: Sin el ID de visitante, DataFast no puede atribuir los ingresos a los canales de marketing.
Gestiona las monedas sin decimales: Algunas monedas, como JPY y KRW, no tienen posiciones decimales. Ajusta la conversión del importe para ellas y para las monedas con tres decimales, como KWD.
Prueba con pagos de ejemplo: Ejecuta el handler con Test this code y confirma que la integración funciona antes de ponerla en producción.
Supervisa el panel de DataFast: Comprueba que los pagos aparezcan con la atribución esperada.
Confía en los reintentos del webhook: DataFast omite un pago cuyo transaction_id ya haya registrado, por lo que una entrega reintentada no crea un duplicado.

Solución de problemas

Payments Not Appearing in DataFast

Verifica que tu clave de API de DataFast sea correcta y esté activa.
Comprueba que el datafast_visitor_id se capture y se almacene en los metadatos del pago.
Comprueba que la transformación del webhook dé el formato correcto al payload.
Verifica que el endpoint esté suscrito a payment.succeeded.
Consulta el panel de DataFast para comprobar si hay mensajes de error o registros de la API.
Abre los intentos de entrega del endpoint en la pestaña Logs de Developer → Webhooks para ver la respuesta de DataFast. Un pago sin ID de visitante se cancela y aparece como correcto.

Revenue Attribution Not Working

Confirma que el script de seguimiento de DataFast esté instalado y ejecutándose en tu sitio web.
Verifica que la cookie datafast_visitor_id esté configurada.
Comprueba que el ID de visitante de los metadatos del pago coincida con el que DataFast registró para la visita.
Captura el ID de visitante antes de crear el checkout.
Consulta la documentación de la Payment API de DataFast para obtener más orientación.

Transformation Errors

Comprueba que el payload coincida con el formato de la Payment API de DataFast.
Comprueba que estén presentes todos los campos obligatorios: amount, currency e transaction_id. Incluye datafast_visitor_id para la atribución.
Comprueba la conversión del importe: divide entre 100 para la mayoría de las monedas, entre 1.000 para las monedas con tres decimales y no lo dividas para las monedas sin decimales.
Verifica que la URL del endpoint sea https://datafa.st/api/v1/payments.
Prueba la transformación con payloads de webhook de ejemplo.

Currency Conversion Issues

Para las monedas sin decimales (BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF y XPF), envía el importe tal cual.
Para las monedas con tres decimales (BHD, IQD, JOD, KWD, LYD, OMR y TND), divide el importe entre 1.000.
Para todas las demás monedas, divide el importe entre 100 para convertirlo de la unidad más pequeña a la unidad principal.
Comprueba que el código de moneda utilice el formato ISO 4217, por ejemplo, USD, EUR o JPY.

Recursos adicionales

DataFast Documentation

Obtén más información sobre la Payment API de DataFast y la atribución de ingresos.

DataFast Dashboard

Consulta los análisis de ingresos y los datos de atribución en tu panel de DataFast.

Para obtener ayuda con esta integración, contacta con el equipo de soporte de Dodo Payments en support@dodopayments.com.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introducción

Cómo Funciona

Comenzando

Guía de implementación

Paso 1: Añadir el ID del visitante a los metadatos del checkout

Paso 2: Enviar los datos del pago a DataFast

Ejemplos de código de transformación

Atribución básica de pagos

Gestión de monedas sin decimales

Pagos de suscripciones

Prácticas recomendadas

Solución de problemas

Recursos adicionales

DataFast Documentation

DataFast Dashboard

​Introducción

​Cómo Funciona

​Comenzando

​Guía de implementación

​Paso 1: Añadir el ID del visitante a los metadatos del checkout

​Paso 2: Enviar los datos del pago a DataFast

​Ejemplos de código de transformación

​Atribución básica de pagos

​Gestión de monedas sin decimales

​Pagos de suscripciones

​Prácticas recomendadas

​Solución de problemas

​Recursos adicionales

DataFast Documentation

DataFast Dashboard

Introducción

Cómo Funciona

Comenzando

Guía de implementación

Paso 1: Añadir el ID del visitante a los metadatos del checkout

Paso 2: Enviar los datos del pago a DataFast

Ejemplos de código de transformación

Atribución básica de pagos

Gestión de monedas sin decimales

Pagos de suscripciones

Prácticas recomendadas

Solución de problemas

Recursos adicionales