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.
Como funciona
Quando um visitante clica em um dos seus links curtos do Dub, o Dub armazena um ID de clique exclusivo no cookiedub_id. Para atribuir vendas aos seus links:
- Capture o ID de clique do Dub no cookie
dub_idao criar o checkout. - Armazene o ID de clique no
metadatado pagamento, junto com o ID do seu cliente no seu sistema (o ID externo). - Envie a venda ao Dub pela Track API quando o pagamento for aprovado.
Pré-requisitos
Antes de configurar essa integração, você precisa de:- Uma conta do Dub com um workspace.
- Acompanhamento de conversões ativado para os seus links.
- 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.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 nometadata 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.

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.
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 ometadata 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 handlerspayment.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 flagis_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 webhookpayment.succeeded. O código usa sua chave de API do Dub; portanto, execute-o no seu servidor, nunca no navegador.
Práticas recomendadas
- 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
customerExternalIdpara obter análises precisas no nível do cliente. - Trate o tráfego orgânico: defina
webhook.cancel = truequando 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
amountde0, 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, definawebhook.cancel = truequandototal_amountfor0. - Reembolsos: se precisar de relatórios precisos de receita, rastreie os reembolsos separadamente.
Solução de problemas
Sales Not Appearing in Dub
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_idfoi 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.
Revenue Attribution Not Working
Revenue Attribution Not Working
- Confirme se os clientes clicam nos seus links curtos do Dub antes do checkout.
- Verifique se o cookie
dub_idestá 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.
Transformation Errors
Transformation Errors
- Verifique se o payload corresponde ao formato da Track Sale API do Dub.
- Verifique se os campos obrigatórios,
customerExternalIdeamount, estão presentes e seclickIdestá 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.
Duplicate Sales Being Tracked
Duplicate Sales Being Tracked
- Rastreie vendas somente em eventos
payment.succeeded, não empayment.processing. - Use um
invoiceIdexclusivo para cada venda. O Dub registra apenas uma venda para cadainvoiceId. - Para renovações, crie
invoiceIda 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.