O Paddle é o provedor de pagamentos como merchant-of-record usado por muitas empresas SaaS na UE — o Paddle lida com o IVA europeu, impostos sobre vendas nos EUA, reembolsos, contestações e conformidade global em seu nome e depois repassa o valor líquido.

Conectar o Paddle ao Zenovay permite que você veja a receita do Paddle ao lado dos seus dados de tráfego — quais campanhas fecham negócios, quais páginas convertem, quais fontes têm o melhor LTV.

Você precisa de apenas UMA coisa: uma chave de API do Paddle com permissão de Escrita. O Zenovay cria o destino do webhook em seu nome, captura o segredo de assinatura via API do Paddle e armazena ambos — criptografados. O mesmo fluxo funciona para Sandbox ou Live; você simplesmente seleciona o ambiente correspondente com o botão Sandbox/Live no formulário.

Configuração (2 minutos)

1
Gerar uma chave de API com permissão de Escrita no Paddle
- Live: vendors.paddle.com/authentication-v2
- Sandbox: sandbox-vendors.paddle.com/authentication-v2
Clique em New API key → nomeie como "Zenovay analytics" → permissão: Write → Create.
O Paddle mostra a chave UMA VEZ. Copie agora. As chaves Live começam com pdl_live_apikey_…; as chaves sandbox começam com pdl_sdbx_apikey_….
2
Cole a chave no Zenovay e clique em Save Configuration
1. Em app.zenovay.com, abra seu website em Domains, vá para Settings e selecione a aba Revenue.
2. Clique no cartão Paddle.
3. Cole a chave de API e defina o botão Sandbox/Live para corresponder (pdl_sdbx_apikey_… as chaves são Sandbox; pdl_live_apikey_… as chaves são Live). Se o botão e o prefixo da chave não corresponderem, a conexão será rejeitada com uma mensagem de erro clara.
4. Clique em Save Configuration.

Pronto. Por baixo dos panos, o Zenovay:

Valida a chave contra o endpoint /event-types do Paddle.
Chama POST /notification-settings para criar um destino de webhook em https://api.zenovay.com/api/webhooks/paddle/<seu-website-id> inscrito nos quatro eventos canônicos (transaction.completed, subscription.created, subscription.updated, subscription.canceled).
Captura o endpoint_secret_key da resposta do Paddle e armazena criptografado.
Muda o cartão para Connected.

Você nunca toca no painel do Paddle. Nunca vê nem copia um segredo de assinatura. Todo webhook do Paddle é verificado usando o segredo armazenado antes de qualquer escrita no banco de dados.

"Onde encontro meu segredo de assinatura no Paddle?" — resposta curta: você não precisa

Esta é a confusão mais comum. O Paddle deliberadamente oculta o segredo de assinatura no painel após a criação do destino. Não há botão "revelar", sem link "mostrar" — apenas Rotate Secret (que invalida o antigo e fornece um novo). Para contas que exibem o segredo no momento da criação, você tem uma janela breve para copiá-lo antes que desapareça.

Esse é um comportamento normal do Paddle, não um bug. Existe por uma razão de segurança: segredos em interfaces visuais vazam para capturas de tela, tickets de suporte e pessoas por cima do ombro.

É exatamente por isso que o fluxo de Connect do Zenovay não exige que você o encontre. Usamos a API do Paddle (que SIM expõe o segredo programaticamente para seus próprios destinos) para buscá-lo automaticamente. Você nunca o toca.

E se eu já criei o destino manualmente?

Tudo bem. Quando você salva o cartão Paddle no Zenovay:

Se já existe um destino em nossa URL, o Zenovay o reutiliza e obtém o segredo via API.
Se estiver inativo (ex: alguém o desativou no painel do Paddle), o Zenovay o reativa.
Sem destinos duplicados, sem limpeza manual.

E se eu quiser configurar manualmente mesmo assim?

Você pode, mas é atrito sem benefício. Se insistir:

Etapas de configuração manual (não recomendado)

No Paddle → Notifications → Destinations → New destination → Webhook.
URL: https://api.zenovay.com/api/webhooks/paddle/YOUR_WEBSITE_ID (seu ID de website é o UUID na URL da página quando você abre o website em Domains em app.zenovay.com; também aparece no topo da aba Revenue de configurações).
Inscreva-se em All events (o Zenovay ignora silenciosamente os que não gerencia).
Salve o destino.
É aqui que a maioria fica presa: o Paddle pode ou não exibir o segredo de assinatura na tela seguinte. Se não exibir:
- Opção A: Rotacione o segredo (Paddle → Destinations → clique em seu destino → Rotate Secret). Copie o novo valor.
- Opção B: Exclua este destino e use o fluxo de Connect do Zenovay (o Zenovay o recriará e obterá o segredo via API).
No Zenovay → cartão Paddle → abra a seção Advanced (optional) após colar sua chave de API → cole o segredo pdl_ntfset_… no campo Webhook Secret.
Salve.

Para 99% dos usuários, basta usar o fluxo de Connect acima e pular isso.

Marque suas transações com o ID do visitante (recomendado)

Para que a atribuição pagamento-à-fonte-de-tráfego funcione com mais precisão, defina o ID anônimo Zenovay do visitante como custom_data ao criar a transação ou o checkout do Paddle em seu servidor:

// Node.js example using Paddle's API directly
const visitorId = req.cookies['zv_visitor_id']; // however your client passes it

await fetch('https://api.paddle.com/transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PADDLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [{ price_id: 'pri_01h…', quantity: 1 }],
    customer_id: paddleCustomerId,
    custom_data: { zenovay_visitor_id: visitorId },
  }),
});

Quando a transação é concluída, o Zenovay lê data.custom_data.zenovay_visitor_id e vincula o pagamento à sessão do visitante — incluindo a fonte, campanha e páginas visitadas antes de pagar.

Se você não definir custom_data, a atribuição ainda funciona via endereço de e-mail do cliente (quando presente no evento), mas é menos precisa — só corresponde se o visitante se identificou anteriormente com o mesmo e-mail.

Qual modelo de atribuição é usado

O Zenovay suporta duas janelas de atribuição:

First-touch — o crédito vai para a fonte da qual o visitante chegou em sua primeira sessão.
Last-touch — o crédito vai para a fonte da qual chegou na sessão que continha o pagamento.

Ambas são calculadas e exibidas lado a lado na aba Revenue.

Passo 5: Testes no Sandbox

A forma correta de verificar sua integração com Sandbox é fazer um checkout de teste real:

No painel sandbox do Paddle, crie um produto e preço de teste.
Use um overlay de checkout ou URL de checkout hospedado em uma página de teste que carregue o seu rastreador Zenovay.
Conclua o checkout com um dos números de cartão de teste do Paddle.
Em cerca de 10 segundos: o Paddle envia um evento transaction.completed real e assinado para o Zenovay. Verifique se chegou carregando a aba Revenue no Zenovay — a captura deve aparecer com o e-mail do comprador + valor.

Se a captura não aparecer após ~30 segundos:

Verifique o badge Verification status no cartão Paddle nas configurações do Zenovay.
Confirme que o modo Sandbox vs Live corresponde em ambos os lados. Um painel Paddle de ambiente sandbox dispara eventos de sandbox-api.paddle.com; se o Zenovay estiver no modo Live, a verificação da assinatura falhará.
Confirme se o destino de notificação ainda está habilitado no Paddle (o Paddle desabilita automaticamente os destinos após 5 respostas 5xx consecutivas; se o Zenovay estava em deploy durante o seu teste, reative-o).

Suporte a moedas

O Paddle retorna valores de transação na menor unidade da moeda (por exemplo, "4999" para USD 49,99). O Zenovay converte isso corretamente por ISO 4217:

Moedas decimais (USD, EUR, GBP, …): divide por 100 → 4999 se torna 49,99.
Moedas sem decimais (JPY, KRW, VND, …): usa o valor como está → 5000 JPY continua 5000.
Moedas com três decimais (BHD, KWD, OMR, …): divide por 1000 → 1500 BHD se torna 1,500.

Você não precisa configurar nada — o Zenovay faz isso automaticamente com base no currency_code do evento.

Trocar do Sandbox para Live

Quando estiver pronto para produção:

No painel Live do Paddle (vendors.paddle.com, não sandbox-vendors), repita o Passo 1 e o Passo 2 para criar um destino de notificação Live e uma chave de API Live.
No Zenovay, clique no cartão Paddle → Disconnect (manter o histórico está correto) → clique novamente para reconectar → cole as credenciais Live → alterne para Live → Salve.

A mesma URL de webhook do Zenovay funciona para ambos os ambientes; o Paddle envia os eventos para o destino que corresponde à sua chave de API ativa.

Desconectar

Abra seu website em Domains → Settings → a aba Revenue → clique no cartão Paddle → Disconnect.

Por padrão, desconectar apenas remove suas credenciais do Paddle. Seus registros de pagamento existentes, histórico de atribuição e dados do painel Revenue permanecem intactos (sujeitos à janela de retenção de dados do seu plano). Você pode reconectar a qualquer momento e continuar de onde parou.

Opcional: também excluir dados históricos do Paddle

O diálogo de desconexão inclui uma caixa de seleção: "Also permanently delete N Paddle records ($X total)". Marque-a apenas se quiser começar do zero — por exemplo, ao descomissionar uma integração de teste ou fazer uma limpeza de privacidade.

Quando marcada, o Zenovay irá:

Excluir todos os eventos de pagamento do Paddle para este website
Excluir todos os registros de pagamento do Paddle para este website
Limpar o campo ID de cliente Paddle em cada usuário identificado (o registro do usuário em si é preservado — eles mantêm o Stripe ID etc.)

A exclusão é executada em uma única transação — se alguma etapa falhar, todas as três são revertidas, para que você nunca fique em um estado de exclusão parcial. A ação é irreversível.

Não se esqueça de desabilitar o destino de notificação no lado do Paddle

Desconectar no Zenovay apenas impede o Zenovay de aceitar eventos. O Paddle continuará disparando o destino em nosso endpoint até que você o desabilite no seu painel do Paddle:

Abra Paddle → Notifications → Destinations.
Encontre o destino apontando para https://api.zenovay.com/api/webhooks/paddle/{seu-website-id}.
Clique nele → alterne para Disabled (ou Delete).

Até que você faça isso, nosso endpoint responde 400 "Webhook not configured for this website" a cada entrega. O Paddle eventualmente desabilita automaticamente o destino após falhas suficientes — mas a remoção explícita é mais limpa e evita que o destino polua seu painel.

Limitações (V1)

Eventos de reembolso ainda não são renderizados. Inscreva-se em adjustment.created / adjustment.updated no seu destino mesmo assim — o Zenovay os ignora silenciosamente hoje e começará a renderizá-los assim que o V2 for lançado.
Os eventos subscription.past_due e subscription.paused são recebidos e registrados com deduplicação, mas ainda não são renderizados no painel. O status da assinatura muda para past_due corretamente, mas você não obtém uma visualização de incidente dedicada.
Uma conta Paddle por website Zenovay. Se você aceitar pagamentos por meio de várias contas do Paddle (ex: uma por subsidiária geográfica), configure cada uma em seu próprio website Zenovay.
Conexão via redirecionamento OAuth não é suportada. Apenas entrada manual de credenciais.

Solução de problemas

"Invalid Paddle API key" ao salvar

Três suspeitos usuais:

Ambiente errado. Uma chave pdl_sdbx_apikey_… com o toggle Live ativado (ou vice-versa) falha na validação. O Zenovay exibe uma mensagem de erro específica — corresponda o toggle ao prefixo.
A chave deve ter permissão de Escrita E não estar revogada. Chaves somente leitura passam na validação, mas falham quando o Zenovay tenta criar o destino (403). Chaves revogadas falham diretamente na validação (401). Gere uma nova chave com escopo de Escrita.
A chave era de outra equipe/conta. As chaves de API do Paddle têm escopo para uma única conta Paddle; colar uma chave de uma conta diferente falha imediatamente.

"Webhook not configured for this website"

Ou você ainda não salvou as credenciais do Paddle no Zenovay, ou está testando a URL errada do webhook. A URL deve incluir o exato ID de website para o website conectado (o UUID na URL da página quando você abre o website em Domains em app.zenovay.com).

"Signature verification failed: replay_window_exceeded"

O Zenovay rejeita eventos de webhook com timestamps mais de 5 minutos fora do horário atual. Isso geralmente indica desalinhamento de relógio do seu lado ou do lado do Paddle. Se você vir isso em um teste novo:

Reinicie seu servidor (desvio de relógio é incomum, mas acontece após longa operação).
Acione novamente o webhook pelo painel do Paddle (Notifications → Deliveries → Resend).

Webhook verificado chega, mas a transação não aparece na aba Revenue

O webhook do Paddle chega em 3 formatos distintos dependendo se o cliente foi criado de forma independente ou como parte de um checkout. O parser do Zenovay é defensivo, mas se você vir uma entrega verificada nos seus logs e nada em Revenue:

Confirme que a entrega retornou 2xx no registro de entrega de Paddle. Uma discrepância de assinatura ou ambiente se mostra como 4xx.
Se falta o email do comprador no evento, Zenovay volta para correspondência por ID de cliente Paddle. A transação está registrada mas não aparecerá nas visualizações de usuário identificado até que o mesmo cliente seja vinculado via um upsert de usuário identificado futuro.
Se ainda não aparece, entre em contato com o suporte em [email protected] com o ID de entrega de Paddle para que possamos rastreá-lo.

Como integro o Paddle para rastreamento de receita?

Configuração (2 minutos)

Gerar uma chave de API com permissão de Escrita no Paddle

Cole a chave no Zenovay e clique em Save Configuration