Dub

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:

Capturar o ID de clique do Dub do cookie dub_id ao criar sessões de checkout
Armazenar o ID de clique nos metadados do pagamento junto com o ID externo do cliente
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:

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

Primeiros passos

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.

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.

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.

Send Sale Data via Webhook

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

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.

Os exemplos abaixo usam POST /payments, que está deprecated. Ele ainda funciona para integrações existentes, mas novas integrações devem usar Checkout Sessions (POST /checkouts) — metadata recebe o valor da mesma forma.

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: 'customer@example.com',
      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("customer@example.com"),
                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: Envie os dados da venda para o Dub

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

Open the Webhook Section

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

Select Dub

Selecione o card de integração do Dub.

Enter API Key

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

Configure Transformation

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

Test & Create

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

Exemplos de código de transformação

Rastreamento básico de vendas

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

Rastrear vendas de assinaturas

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

Rastrear vendas com exclusão de impostos

Envie apenas o valor antes dos impostos ao Dub para um rastreamento preciso da receita:

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

Rastrear 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 no lado do cliente

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

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

Boas práticas

Capture o ID do clique antecipadamente: armazene o ID do 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 do clique nos metadados: sem o ID do clique, o Dub não pode atribuir a receita aos seus links
Use IDs externos de forma consistente: passe o mesmo ID de cliente usado no seu sistema para obter análises precisas no nível do cliente
Lide adequadamente com o tráfego orgânico: defina webhook.cancel = true quando não houver um ID de clique para evitar chamadas desnecessárias à API
Teste com pagamentos de exemplo: verifique se a integração funciona corretamente antes de entrar em produção
Monitore seu dashboard do Dub: confirme 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.)
Períodos de teste gratuitos: pagamentos de $0 não são rastreados como vendas
Reembolsos: considere rastrear os reembolsos separadamente, se necessário, para obter 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
Verifique 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 rastreamento de conversões está habilitado 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
Verifique se os IDs de clique correspondem entre a criação do checkout e a conclusão do pagamento
Certifique-se de capturar o ID do 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
Verifique 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 rastrear 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 rastreamento de conversões e análise do Dub.

Dub Track Sale API

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

Dub Dashboard

Acesse seu dashboard do Dub para visualizar as análises de conversão e os dados de atribuição.

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 endereço support@dodopayments.com para obter assistência com a integração.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Introdução

Como funciona

Pré-requisitos

Primeiros passos

Guia de implementação

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

Etapa 2: Envie os dados da venda para o Dub

Exemplos de código de transformação

Rastreamento básico de vendas

Rastrear vendas de assinaturas

Rastrear vendas com exclusão de impostos

Rastrear vendas com nomes de eventos personalizados

Alternativa: implementação no lado do cliente

Boas práticas

Observações importantes

Solução de problemas

Recursos adicionais

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

​Introdução

​Como funciona

​Pré-requisitos

​Primeiros passos

​Guia de implementação

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

​Etapa 2: Envie os dados da venda para o Dub

​Exemplos de código de transformação

​Rastreamento básico de vendas

​Rastrear vendas de assinaturas

​Rastrear vendas com exclusão de impostos

​Rastrear vendas com nomes de eventos personalizados

​Alternativa: implementação no lado do cliente

​Boas práticas

​Observações importantes

​Solução de problemas

​Recursos adicionais

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

Introdução

Como funciona

Pré-requisitos

Primeiros passos

Guia de implementação

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

Etapa 2: Envie os dados da venda para o Dub

Exemplos de código de transformação

Rastreamento básico de vendas

Rastrear vendas de assinaturas

Rastrear vendas com exclusão de impostos

Rastrear vendas com nomes de eventos personalizados

Alternativa: implementação no lado do cliente

Boas práticas

Observações importantes

Solução de problemas

Recursos adicionais