Skip to main content

Introdução

Dub é uma plataforma de atribuição de links para links curtos, acompanhamento de conversões e programas de afiliados. Com essa integração, o Dub registra um evento de conversão de venda sempre que um cliente paga pelo Dodo Payments, permitindo medir o retorno das suas campanhas de marketing e programas de indicação. O Dub registra uma venda quando um cliente:
  • Conclui um pagamento único
  • Assina um plano pago
  • Faz um pagamento de assinatura recorrente
Essa integração exige uma conta do Dub com o acompanhamento de conversões ativado nos seus links. O acompanhamento de conversões do Dub exige um plano Business ou superior.
Integração com programa de afiliados: essa integração também funciona com o Dub Partners, o produto de programa de afiliados do Dub. O Dub atribui as vendas aos links de afiliados dos seus parceiros, permitindo acompanhar indicações, comissões e o desempenho de cada parceiro. Para configurar um programa de afiliados, consulte o guia do recurso de Afiliados.

Como funciona

Quando um visitante clica em um dos seus links curtos do Dub, o Dub armazena um ID de clique exclusivo no cookie dub_id. Para atribuir vendas aos seus links:
  1. Capture o ID de clique do Dub no cookie dub_id ao criar o checkout.
  2. Armazene o ID de clique no metadata do pagamento, junto com o ID do seu cliente no seu sistema (o ID externo).
  3. Envie a venda ao Dub pela Track API quando o pagamento for aprovado.
O Dub associa cada venda aprovada ao clique original no link, atribuindo a conversão a esse link.

Pré-requisitos

Antes de configurar essa integração, você precisa de:
  1. Uma conta do Dub com um workspace.
  2. Acompanhamento de conversões ativado para os seus links.
  3. Uma chave de API do Dub, criada 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. O Dub então registra eventos de venda para clientes que chegam por esses links.
Para ativar o acompanhamento de conversões, consulte a documentação do Dub.
2

Get Your Dub API Key

No seu painel do Dub, acesse Settings → API Keys e crie uma chave de API com o escopo conversions.write.
Mantenha sua chave de API segura. Nunca a exponha em código do lado do cliente.
3

Capture Click ID in Checkout

Ao criar um checkout, leia o ID de clique do Dub no cookie e adicione-o ao metadata do pagamento. Consulte a Etapa 1.
4

Send Sale Data via Webhook

Crie um endpoint de webhook que envie cada venda à Track API do Dub quando um pagamento for aprovado. Consulte a Etapa 2.
5

Done

Os eventos de conversão de vendas aparecem no painel de analytics do Dub, atribuídos 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 um checkout, leia o ID de clique do Dub no cookie e inclua-o no metadata do pagamento, junto com o ID externo do seu cliente.
Os exemplos abaixo usam POST /payments, 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.

Etapa 2: Envie os dados da venda para o Dub

Crie um endpoint de webhook que envie os dados da venda à Track API do Dub quando um pagamento for aprovado.
1

Open the Webhook Section

No dashboard do Dodo Payments, acesse Developer → Webhooks e clique em Add endpoint.
Add endpoint dialog with Dub.co selected in the Integration dropdown
2

Select Dub

Em Integration, selecione Dub.co.
3

Enter API Key

Em API key, cole sua chave de API do Dub. O Dodo Payments a envia no cabeçalho Authorization de cada entrega.
API key field for the Dub integration
4

Check the URL and Events

Se Endpoint URL estiver vazio, insira https://api.dub.co/track/sale. Em Subscribed events, selecione os eventos tratados pela sua transformação, como payment.succeeded.
5

Configure Transformation

Em Transformation code, edite o handler para formatar os dados de pagamento para a Track Sale API do Dub. Comece pelos exemplos.
6

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 envia uma venda ao Dub somente quando o metadata tem um ID de clique. Para tráfego orgânico, sem ID de clique, ele define webhook.cancel = true, portanto nenhuma solicitação é enviada ao Dub; a entrega cancelada ainda aparece como bem-sucedida nos logs do webhook. O corpo da solicitação segue a Track Sale API do Dub: customerExternalId e amount são obrigatórios, e paymentProcessor é custom, porque a lista de processadores de pagamento do Dub não contém um valor para Dodo Payments. O Dub recebe amount na mesma unidade usada pelos valores do Dodo Payments: centavos para moedas com duas casas decimais e o número inteiro completo para moedas sem casas decimais, como JPY. Os exemplos passam o valor sem alterações.

Rastreamento básico de vendas

Rastreie uma venda quando um pagamento for aprovado:
basic_sale.js

Rastrear vendas de assinaturas

Rastreie tanto as assinaturas iniciais quanto os pagamentos recorrentes. Use este handler para assinaturas em vez dos handlers payment.succeeded, e não junto com eles: cada pagamento de assinatura também dispara payment.succeeded, portanto tratar os dois eventos registra cada venda duas vezes. Consulte o Guia de integração de assinaturas. O handler lê o ID de clique a partir do metadata da assinatura; portanto, passe os mesmos metadados ao criar a assinatura. Para renovações, invoiceId combina o ID da assinatura com previous_billing_date, o início do período de cobrança atual, para que uma entrega repetida reutilize o mesmo invoiceId.
subscription_sale.js

Rastrear vendas com exclusão de impostos

Envie ao Dub somente o valor antes dos impostos, para que a receita no Dub não inclua impostos:
sale_without_tax.js

Rastrear vendas com nomes de eventos personalizados

Use nomes de eventos personalizados para categorizar diferentes tipos de vendas. O exemplo lê uma flag is_upgrade que você define no metadata do pagamento:
custom_events.js

Alternativa: implementação no lado do cliente

Para rastrear vendas pelo seu próprio servidor em vez de usar uma transformação de webhook, chame a Track API do Dub diretamente após um pagamento aprovado, por exemplo, no seu handler de webhook payment.succeeded. O código usa sua chave de API do Dub; portanto, execute-o no seu servidor, nunca no navegador.

Práticas recomendadas

Capture o ID de clique antecipadamente: armazene o ID de clique do Dub o mais cedo possível no fluxo de checkout, para que a atribuição permaneça precisa mesmo que o cliente saia e retorne mais tarde.
  • 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: passe sempre o mesmo ID de cliente do seu sistema como customerExternalId para obter análises precisas no nível do cliente.
  • Trate o tráfego orgânico: defina webhook.cancel = true quando não houver um ID de clique, para evitar chamadas de API desnecessárias.
  • Teste com pagamentos de exemplo: execute o handler usando Test this code e confirme que a integração funciona antes de entrar em produção.
  • Monitore seu dashboard do Dub: verifique se as vendas aparecem com a atribuição esperada.

Observações importantes

  • Formato do valor: o Dub espera valores em centavos para moedas com duas casas decimais (por exemplo, $10.00 é 1000) e o número inteiro completo para moedas sem casas decimais, como JPY.
  • Moeda: use códigos de moeda ISO 4217, como USD, EUR e GBP. O Dub converte cada venda para USD usando a taxa de câmbio mais recente.
  • Períodos de teste gratuitos: a Track Sale API do Dub aceita um amount de 0, e os exemplos não ignoram pagamentos de $0; portanto, cada pagamento de $0 chega ao Dub como uma venda. Para ignorar pagamentos de $0, defina webhook.cancel = true quando total_amount for 0.
  • Reembolsos: se precisar de relatórios precisos de receita, rastreie os reembolsos separadamente.

Solução de problemas

  • Verifique se sua chave de API do Dub está correta e possui o escopo conversions.write.
  • Verifique se o dub_click_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.
  • Confirme se o rastreamento de conversões está ativado para seus links do Dub.
  • Abra as tentativas de entrega do endpoint na guia Logs de Developer → Webhooks para ver a resposta do Dub. Um pagamento sem ID de clique é cancelado e aparece como bem-sucedido.
  • Confirme se os clientes clicam nos seus links curtos do Dub antes do checkout.
  • Verifique se o cookie dub_id está definido no seu domínio.
  • Verifique se o ID de clique nos metadados do pagamento corresponde ao clique realizado pelo cliente.
  • Capture o ID de clique antes de criar o checkout.
  • Verifique se o payload corresponde ao formato da Track Sale API do Dub.
  • Verifique se os campos obrigatórios, customerExternalId e amount, estão presentes e se clickId está definido para atribuição.
  • Verifique se o valor é um número inteiro na menor unidade da moeda, não um decimal.
  • Verifique se a URL do endpoint é https://api.dub.co/track/sale.
  • Teste a transformação com payloads de webhook de exemplo.
  • Rastreie vendas somente em eventos payment.succeeded, não em payment.processing.
  • Use um invoiceId exclusivo para cada venda. O Dub registra apenas uma venda para cada invoiceId.
  • Para renovações, crie invoiceId a partir do ID da assinatura e do período de cobrança, como em Rastrear vendas de assinaturas. Um valor que muda a cada entrega, como o horário atual, registra uma venda duplicada quando uma entrega é repetida.

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

Veja os dados de análise de conversões e atribuição no seu dashboard do Dub.

Webhook Events Guide

Navegue por todos os eventos de webhook do Dodo Payments.
Para obter ajuda com essa integração, entre em contato com o suporte do Dodo Payments pelo e-mail support@dodopayments.com.
Última modificação em 26 de setembro de 2026