Skip to main content

Introduction

Dub es una plataforma de atribución de enlaces para enlaces cortos, seguimiento de conversiones y programas de afiliados. Con esta integración, Dub registra un evento de conversión de venta cada vez que un cliente paga a través de Dodo Payments, para que puedas medir el rendimiento de tus campañas de marketing y programas de referidos. Dub registra una venta cuando un cliente:
  • Completa un pago único
  • Se suscribe a un plan de pago
  • Realiza un pago de suscripción recurrente
Esta integración requiere una cuenta de Dub con el seguimiento de conversiones habilitado en tus enlaces. El seguimiento de conversiones de Dub requiere un plan Business o superior.
Integración con programas de afiliados: Esta integración también funciona con Dub Partners, el producto de programas de afiliados de Dub. Dub atribuye las ventas a los enlaces de afiliado de tus partners, para que puedas realizar un seguimiento de las referencias, las comisiones y el rendimiento de cada partner. Para configurar un programa de afiliados, consulta la guía de la función de afiliados.

How It Works

Cuando un visitante hace clic en uno de tus enlaces cortos de Dub, Dub almacena un ID de clic único en la cookie dub_id. Para atribuir las ventas a tus enlaces:
  1. Captura el ID de clic de Dub de la cookie dub_id cuando crees el checkout.
  2. Almacena el ID de clic en el metadata del pago, junto con el ID de tu cliente en tu sistema (el ID externo).
  3. Envía la venta a Dub mediante su Track API cuando el pago se complete correctamente.
Dub relaciona cada venta completada correctamente con el clic en el enlace original, lo que atribuye la conversión a ese enlace.

Prerequisites

Antes de configurar esta integración, necesitas:
  1. Una cuenta de Dub con un workspace.
  2. El seguimiento de conversiones habilitado para tus enlaces.
  3. Una clave de API de Dub, que puedes crear en tu panel de Dub, en Settings → API Keys.

Getting Started

1

Enable Conversion Tracking in Dub

En tu panel de Dub, habilita el seguimiento de conversiones para los enlaces cuyas ventas quieras rastrear. Dub registrará eventos de venta de los clientes que lleguen a través de esos enlaces.
Para habilitar el seguimiento de conversiones, consulta la documentación de Dub.
2

Get Your Dub API Key

En tu panel de Dub, ve a Settings → API Keys y crea una clave de API con el alcance conversions.write.
Mantén tu clave de API segura. Nunca la expongas en código del lado del cliente.
3

Capture Click ID in Checkout

Cuando crees un checkout, lee el ID de clic de Dub de la cookie y añádelo al metadata del pago. Consulta el paso 1.
4

Send Sale Data via Webhook

Crea un endpoint de webhook que envíe cada venta a la Track API de Dub cuando un pago se complete correctamente. Consulta el paso 2.
5

Done

Los eventos de conversión de ventas aparecen en tu panel de analíticas de Dub, atribuidos a tus enlaces.

Implementation Guide

Step 1: Add Click ID and Customer ID to Checkout Metadata

Cuando crees un checkout, lee el ID de clic de Dub de la cookie e inclúyelo en el metadata del pago, junto con el ID externo de tu cliente.
Los ejemplos siguientes usan POST /payments, que está obsoleto. Sigue funcionando para integraciones existentes, pero las integraciones nuevas deben usar Checkout Sessions (POST /checkouts), que aceptan metadata de la misma manera.

Paso 2: Envía los datos de ventas a Dub

Crea un endpoint de webhook que envíe los datos de la venta a la Track API de Dub cuando un pago se complete correctamente.
1

Open the Webhook Section

En el dashboard de Dodo Payments, ve a Developer → Webhooks y haz clic en Add endpoint.
Diálogo para añadir un endpoint con Dub.co seleccionado en el menú desplegable Integration
2

Select Dub

En Integration, selecciona Dub.co.
3

Enter API Key

En API key, pega tu clave de API de Dub. Dodo Payments la envía en el encabezado Authorization de cada entrega.
Campo de clave de API para la integración de Dub
4

Check the URL and Events

Si Endpoint URL está vacío, introduce https://api.dub.co/track/sale. En Subscribed events, selecciona los eventos que gestiona tu transformación, como payment.succeeded.
5

Configure Transformation

En Transformation code, edita el handler para dar formato a los datos de pago para la API Track Sale de Dub. Empieza con los ejemplos.
6

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 envía una venta a Dub solo cuando metadata tiene un ID de clic. Para el tráfico orgánico, sin ID de clic, establece webhook.cancel = true, por lo que no se envía ninguna solicitud a Dub; la entrega cancelada sigue apareciendo como exitosa en los logs del webhook. El cuerpo de la solicitud sigue la API Track Sale de Dub: customerExternalId e amount son obligatorios, y paymentProcessor es custom, porque la lista de procesadores de pago de Dub no incluye un valor para Dodo Payments. Dub toma amount en la misma unidad que los importes de Dodo Payments: centavos para monedas con dos decimales y el entero completo para monedas sin decimales, como JPY. Los ejemplos pasan el importe sin cambios.

Seguimiento básico de ventas

Registra una venta cuando un pago se realiza correctamente:
basic_sale.js

Seguimiento de ventas de suscripciones

Registra tanto las suscripciones iniciales como los pagos recurrentes. Usa este handler para las suscripciones en lugar de los handlers de payment.succeeded, no junto con ellos: cada pago de suscripción también activa payment.succeeded, por lo que gestionar ambos eventos registra cada venta dos veces. Consulta la guía de integración de suscripciones. El handler lee el ID de clic de metadata de la suscripción, así que pasa los mismos metadatos cuando crees la suscripción. Para las renovaciones, invoiceId combina el ID de la suscripción con previous_billing_date, el inicio del periodo de facturación actual, por lo que una entrega reintentada reutiliza el mismo invoiceId.
subscription_sale.js

Seguimiento de ventas sin impuestos

Envía a Dub solo el importe antes de impuestos, para que los ingresos en Dub excluyan los impuestos:
sale_without_tax.js

Seguimiento de ventas con nombres de eventos personalizados

Usa nombres de eventos personalizados para categorizar distintos tipos de ventas. El ejemplo lee un indicador is_upgrade que estableces en metadata del pago:
custom_events.js

Alternativa: implementación del lado del cliente

Para realizar el seguimiento de ventas desde tu propio servidor en lugar de hacerlo mediante una transformación de webhook, llama directamente a la API Track de Dub después de un pago exitoso, por ejemplo, desde tu handler de webhook payment.succeeded. El código utiliza tu clave de API de Dub, así que ejecútalo en tu servidor, nunca en el navegador.

Prácticas recomendadas

Captura el ID de clic pronto: almacena el ID de clic de Dub lo antes posible en el flujo de checkout para que la atribución siga siendo precisa aunque el cliente abandone el proceso y vuelva más tarde.
  • Incluye el ID de clic en los metadatos: sin el ID de clic, Dub no puede atribuir los ingresos a tus enlaces.
  • Usa los IDs externos de forma coherente: pasa siempre el mismo ID de cliente de tu sistema como customerExternalId para obtener análisis precisos a nivel de cliente.
  • Gestiona el tráfico orgánico: establece webhook.cancel = true cuando no haya un ID de clic para evitar llamadas innecesarias a la API.
  • 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 tu dashboard de Dub: comprueba que las ventas aparezcan con la atribución esperada.

Notas importantes

  • Formato del importe: Dub espera los importes en centavos para monedas con dos decimales (por ejemplo, $10.00 es 1000) y el entero completo para monedas sin decimales, como JPY.
  • Moneda: usa códigos de moneda ISO 4217, como USD, EUR y GBP. Dub convierte cada venta a USD según el tipo de cambio más reciente.
  • Pruebas gratuitas: la API Track Sale de Dub acepta un amount de 0, y los ejemplos no omiten los pagos de $0, por lo que cada pago de $0 llega a Dub como una venta. Para omitir los pagos de $0, establece webhook.cancel = true cuando total_amount sea 0.
  • Reembolsos: si necesitas informes precisos de ingresos, realiza el seguimiento de los reembolsos por separado.

Solución de problemas

  • Verifica que tu clave de API de Dub sea correcta y tenga el alcance conversions.write.
  • Comprueba que dub_click_id se capture y 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.
  • Confirma que el seguimiento de conversiones esté habilitado para tus enlaces de Dub.
  • Abre los intentos de entrega del endpoint en la pestaña Logs de Developer → Webhooks para ver la respuesta de Dub. Un pago sin ID de clic se cancela y aparece como exitoso.
  • Confirma que los clientes hagan clic en tus enlaces cortos de Dub antes del checkout.
  • Verifica que la cookie dub_id esté establecida en tu dominio.
  • Comprueba que el ID de clic de los metadatos del pago coincida con el clic que realizó el cliente.
  • Captura el ID de clic antes de crear el checkout.
  • Comprueba que el payload coincida con el formato de la API Track Sale de Dub.
  • Comprueba que los campos obligatorios, customerExternalId e amount, estén presentes y que clickId esté establecido para la atribución.
  • Comprueba que el importe sea un entero en la unidad monetaria más pequeña, no un decimal.
  • Verifica que la URL del endpoint sea https://api.dub.co/track/sale.
  • Prueba la transformación con payloads de webhook de ejemplo.
  • Registra las ventas solo en eventos payment.succeeded, no en payment.processing.
  • Usa un invoiceId único para cada venta. Dub registra solo una venta por cada invoiceId.
  • Para las renovaciones, crea invoiceId a partir del ID de la suscripción y del periodo de facturación, como se muestra en Seguimiento de ventas de suscripciones. Un valor que cambie en cada entrega, como la hora actual, registra una venta duplicada cuando se reintenta una entrega.

Recursos adicionales

Dub Conversions Documentation

Obtén más información sobre las funciones de seguimiento de conversiones y análisis de Dub.

Dub Track Sale API

Consulta la referencia completa de la API del endpoint Track Sale de Dub.

Dub Dashboard

Consulta los análisis de conversiones y los datos de atribución en tu dashboard de Dub.

Webhook Events Guide

Explora todos los eventos de webhook de Dodo Payments.
Para obtener ayuda con esta integración, contacta con el equipo de soporte de Dodo Payments en support@dodopayments.com.
Última modificación el 26 de septiembre de 2026