Dub

Acompanhe eventos de conversão de vendas no Dub quando os clientes concluírem compras por meio de <Info>.

​

Introdução

Dub é uma poderosa plataforma de gerenciamento de links que ajuda você a criar, compartilhar e acompanhar links curtos. Ao integrar Dodo Payments ao Dub, você pode acompanhar automaticamente eventos de conversão de vendas quando os clientes concluírem compras, permitindo medir o ROI das suas campanhas de marketing e programas de indicação.

Um evento de “venda” é registrado no Dub quando um cliente:

• Conclui um pagamento único
• Assina um plano pago
• Efetua um pagamento de assinatura recorrente

Essa integração requer uma conta do Dub com o acompanhamento de conversões ativado nos seus links.

Integração com o programa de afiliados: essa integração também funciona perfeitamente com o Dub Partners para acompanhar indicações e comissões de afiliados. Use o acompanhamento de conversões do Dub para atribuir vendas aos seus links de afiliado e medir o desempenho dos parceiros. Saiba mais sobre como configurar programas de afiliados no nosso guia do recurso de Afiliados.

​

Como funciona

O Dub acompanha os visitantes por meio de um ID de clique exclusivo (dub_id), armazenado em um cookie quando os usuários clicam nos seus links curtos do Dub. Para atribuir vendas aos seus links, você precisa:

1. Capturar o ID de clique do Dub do cookie dub_id ao criar sessões de checkout
2. Armazenar o ID de clique nos metadados do pagamento junto com o ID externo do cliente
3. Enviar os dados da venda ao Dub quando os pagamentos forem bem-sucedidos usando a Track API

Isso permite que o Dub associe vendas bem-sucedidas ao clique original no link, oferecendo atribuição completa de conversões.

​

Pré-requisitos

Antes de configurar essa integração, certifique-se de ter:

1. Uma conta do Dub com um workspace
2. O acompanhamento de conversões ativado para seus links
3. Sua chave de API do Dub (disponível no painel do Dub em Settings → API Keys)

​

Primeiros passos

1. Enable Conversion Tracking in Dub

   No painel do Dub, ative o acompanhamento de conversões para os links cujas vendas você deseja acompanhar. Isso permite que o Dub registre eventos de venda quando os clientes concluírem compras.

   Saiba mais sobre como ativar o acompanhamento de conversões na documentação do Dub.

2. Get Your Dub API Key

   Acesse o painel do Dub → Settings → API Keys e crie uma nova chave de API com o escopo conversions.write.

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

3. Capture Click ID in Checkout

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

4. Send Sale Data via Webhook

   Configure um webhook para enviar os dados da venda à Track API do Dub quando os pagamentos forem bem-sucedidos.

5. Done!

   Os eventos de conversão de vendas agora aparecerão no painel de analytics do Dub, com atribuição completa aos seus links.

​

Guia de implementação

​

Etapa 1: adicionar o ID de clique e o ID do cliente aos metadados do checkout

Ao criar uma sessão de checkout, capture o ID de clique do Dub do cookie e inclua-o nos metadados do pagamento junto com o ID externo do cliente.

Next.js

import { cookies } from 'next/headers';
import DodoPayments from 'dodopayments';

const client = new DodoPayments();

export async function createCheckout(productId: string, customerId: string) {
  // Capture Dub click ID from cookie
  const dubClickId = cookies().get('dub_id')?.value;

  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: '[e-mail]',
      name: 'John Doe',
    },
    product_cart: [{ product_id: productId, quantity: 1 }],
    metadata: {
      dub_click_id: dubClickId,           // Store Dub click ID
      dub_external_id: customerId,        // Store your customer's unique ID
    },
  });

  return payment;
}

const express = require('express');
const DodoPayments = require('dodopayments').default;
const router = express.Router();

const client = new DodoPayments();

router.post('/create-checkout', async (req, res) => {
  // Capture Dub click ID from cookie
  const dubClickId = req.cookies?.dub_id;

  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: req.body.email,
      name: req.body.name,
    },
    product_cart: [{ product_id: req.body.productId, quantity: 1 }],
    metadata: {
      dub_click_id: dubClickId,           // Store Dub click ID
      dub_external_id: req.body.customerId, // Store your customer's unique ID
    },
  });

  res.json({ payment });
});

from fastapi import FastAPI, Request
from dodopayments import DodoPayments

app = FastAPI()
client = DodoPayments()

@app.post("/create-checkout")
async def create_checkout(request: Request):
    # Capture Dub click ID from cookie
    dub_click_id = request.cookies.get("dub_id")

    body = await request.json()

    payment = client.payments.create(
        billing={
            "city": "New York",
            "country": "US",
            "state": "NY",
            "street": "123 Main St",
            "zipcode": "10001",
        },
        customer={
            "email": body["email"],
            "name": body["name"],
        },
        product_cart=[{"product_id": body["product_id"], "quantity": 1}],
        metadata={
            "dub_click_id": dub_click_id,          # Store Dub click ID
            "dub_external_id": body["customer_id"], # Store your customer's unique ID
        },
    )

    return {"payment": payment}

package main

import (
    "context"

    "github.com/dodopayments/dodopayments-go"
)

func createCheckout(dubClickId, customerId, productId string) (*dodopayments.PaymentNewResponse, error) {
    client := dodopayments.NewClient()

    payment, err := client.Payments.New(context.Background(), dodopayments.PaymentNewParams{
        Billing: dodopayments.F(dodopayments.BillingAddressParam{
            City:    dodopayments.F("New York"),
            Country: dodopayments.F(dodopayments.CountryCodeUs),
            State:   dodopayments.F("NY"),
            Street:  dodopayments.F("123 Main St"),
            Zipcode: dodopayments.F("10001"),
        }),
        Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
            dodopayments.NewCustomerParam{
                Email: dodopayments.F("[e-mail]"),
                Name:  dodopayments.F("John Doe"),
            },
        ),
        ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
            ProductID: dodopayments.F(productId),
            Quantity:  dodopayments.F(int64(1)),
        }}),
        Metadata: dodopayments.F(map[string]string{
            "dub_click_id":    dubClickId, // Store Dub click ID
            "dub_external_id": customerId, // Store your customer's unique ID
        }),
    })

    return payment, err
}

​

Etapa 2: enviar os dados da venda ao Dub

Configure um endpoint de webhook para enviar os dados da venda à Track API do Dub quando os pagamentos forem bem-sucedidos.

1. Open the Webhook Section

   No painel do Dodo Payments, acesse Webhooks → + Add Endpoint e expanda o menu suspenso de integrações.

   
2. Select Dub

   Selecione o card de integração Dub.

3. Enter API Key

   Informe sua chave de API do Dub no campo de configuração.

   
4. Configure Transformation

   Edite o código de transformação para formatar os dados de pagamento para a Track Sale API do Dub.

5. Test & Create

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

​

Exemplos de código de transformação

​

Acompanhamento básico de vendas

Acompanhe as vendas quando os pagamentos forem bem-sucedidos:

basic_sale.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    // Only send to Dub if click ID exists in metadata
    if (payment.metadata && payment.metadata.dub_click_id) {
      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount, // Ensure the amount is in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          customer_email: payment.customer.email,
          customer_name: payment.customer.name,
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​

Acompanhar vendas de assinaturas

Acompanhe tanto as assinaturas iniciais quanto os pagamentos recorrentes:

subscription_sale.js

function handler(webhook) {
  const data = webhook.payload.data;

  // Track initial subscription activation
  if (webhook.eventType === "subscription.active") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount, // Amount in cents
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: data.subscription_id,
        eventName: "Subscription Started",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          billing_interval: data.payment_frequency_interval,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  // Track recurring subscription payments
  if (webhook.eventType === "subscription.renewed") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount,
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: `${data.subscription_id}_${Date.now()}`,
        eventName: "Subscription Renewed",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  return webhook;
}

​

Acompanhar vendas excluindo impostos

Envie ao Dub apenas o valor antes dos impostos para acompanhar a receita com precisão:

sale_without_tax.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Calculate pre-tax amount (total minus tax)
      const preTaxAmount = payment.total_amount - (payment.tax || 0);

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: preTaxAmount, // Pre-tax amount in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          total_amount: payment.total_amount,
          tax_amount: payment.tax || 0,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​

Acompanhar vendas com nomes de eventos personalizados

Use nomes de eventos personalizados para categorizar diferentes tipos de vendas:

custom_events.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Determine event name based on payment type
      let eventName = "Purchase";
      if (payment.subscription_id) {
        eventName = "Subscription Purchase";
      } else if (payment.metadata && payment.metadata.is_upgrade) {
        eventName = "Plan Upgrade";
      }

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount,
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        eventName: eventName,
        metadata: {
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​

Alternativa: implementação do lado do cliente

Se preferir acompanhar as vendas do seu servidor em vez de usar webhooks, você pode chamar diretamente a Track API do Dub após um pagamento bem-sucedido:

Next.js (Server Action)

'use server';

import { Dub } from 'dub';

const dub = new Dub();

export async function trackSale(
  paymentId: string,
  clickId: string,
  customerId: string,
  amount: number,
  currency: string
) {
  await dub.track.sale({
    clickId: clickId,
    externalId: customerId,
    amount: amount,
    currency: currency,
    paymentProcessor: 'dodo',
    invoiceId: paymentId,
  });
}

const { Dub } = require('dub');

const dub = new Dub();

async function trackSale(payment) {
  if (payment.metadata?.dub_click_id) {
    await dub.track.sale({
      clickId: payment.metadata.dub_click_id,
      externalId: payment.metadata.dub_external_id,
      amount: payment.total_amount,
      currency: payment.currency,
      paymentProcessor: 'dodo',
      invoiceId: payment.payment_id,
    });
  }
}

​

Práticas recomendadas

Capture o ID de clique antecipadamente: armazene o ID de clique do Dub o quanto antes no fluxo de checkout para garantir uma atribuição precisa, mesmo que o usuário saia e retorne mais tarde.

• Sempre inclua o ID de clique nos metadados: sem o ID de clique, o Dub não consegue atribuir a receita aos seus links
• Use IDs externos de forma consistente: envie o mesmo ID de cliente usado no seu sistema para obter analytics precisos no nível do cliente
• Trate o tráfego orgânico adequadamente: defina webhook.cancel = true quando não houver um ID de clique para evitar chamadas de API desnecessárias
• Teste com pagamentos de exemplo: verifique se a integração funciona corretamente antes de entrar em produção
• Monitore o painel do Dub: confira se as vendas estão aparecendo corretamente com a atribuição adequada

​

Observações importantes

• Formato do valor: o Dub espera valores em centavos (por exemplo, $10.00 = 1000)
• Moeda: use códigos de moeda ISO 4217 (USD, EUR, GBP etc.)
• Testes gratuitos: pagamentos de $0 não são registrados como vendas
• Reembolsos: considere acompanhar os reembolsos separadamente, se necessário, para gerar relatórios precisos de receita

​

Solução de problemas

Sales not appearing in Dub

• Verifique se sua chave de API do Dub está correta e possui o escopo conversions.write
• Confira se o dub_click_id está sendo capturado e armazenado nos metadados do pagamento
• Certifique-se de que a transformação do webhook está formatando o payload corretamente
• Verifique se o webhook está sendo acionado em eventos payment.succeeded
• Confirme se o acompanhamento de conversões está ativado para seus links do Dub

Revenue attribution not working

• Confirme se os usuários estão clicando nos seus links curtos do Dub antes do checkout
• Verifique se o cookie dub_id está sendo definido corretamente no seu domínio
• Confira se os IDs de clique correspondem entre a criação do checkout e a conclusão do pagamento
• Certifique-se de capturar o ID de clique antes de criar a sessão de checkout

Transformation errors

• Valide se a estrutura JSON corresponde ao formato da Track Sale API do Dub
• Confira se todos os campos obrigatórios (clickId, externalId, amount) estão presentes
• Certifique-se de que o valor esteja em centavos (inteiro, não decimal)
• Verifique se a URL do endpoint da API está correta: https://api.dub.co/track/sale
• Teste a transformação com payloads de webhook de exemplo

Duplicate sales being tracked

• Certifique-se de acompanhar apenas eventos payment.succeeded, não payment.processing
• Use valores invoiceId exclusivos para cada venda
• Para assinaturas, acrescente timestamps ou o período de cobrança para evitar duplicatas nas renovações

​

Recursos adicionais

Dub Conversions Documentation

Saiba mais sobre os recursos de acompanhamento de conversões e analytics do Dub.

Dub Track Sale API

Consulte a referência completa da API para o endpoint Track Sale do Dub.

Dub Dashboard

Acesse o painel do Dub para visualizar os dados de analytics e atribuição de conversões.

Webhook Events Guide

Saiba mais sobre todos os eventos de webhook disponíveis do Dodo Payments.

Precisa de ajuda? Entre em contato com o suporte do Dodo Payments pelo e-mail [e-mail] para obter ajuda com a integração.