Pular para o conteúdo principal
Zenovay
Pro Plano15 minutesIntermediário

Como integro o PayPal para rastreamento de receita?

Conecte o Zenovay à sua conta PayPal para atribuir receita às fontes de tráfego, campanhas e visitantes individuais. Configuração que começa pelo Sandbox, com três credenciais e verificação de assinatura de webhook.

paypalrevenueattributionintegrationwebhooks
Última atualização:

Conectar o PayPal permite que o Zenovay mostre a receita ao lado dos seus dados de tráfego — qual fonte de marketing produziu o cliente pagante, em qual página ele converteu, qual campanha fechou o negócio.

Você precisa de três coisas da sua conta no PayPal Developer: um Client ID, um Client Secret e um Webhook ID. Você cria o webhook no seu painel do PayPal (o Zenovay mostra a URL exata para colar) e copia seu ID devolta para o Zenovay. Recomendamos configurar primeiro o Sandbox para verificar se está tudo funcionando e, depois, mudar para o Live.

⚠️ Importante — dica de teste que você precisa ler primeiro

O Webhooks Simulator do PayPal (o botão "Send Test" no PayPal Developer Dashboard) envia eventos simulados que não podem ter a assinatura verificada, por design. Esse comportamento é documentado pelo próprio PayPal — o simulador vincula as assinaturas a um WEBHOOK_ID de placeholder, não ao seu Webhook ID real, então a API de verificação sempre retorna FAILURE para eventos do simulador.

Para verificar se a sua integração realmente funciona, faça um checkout real no Sandbox (Etapa 5 abaixo) — isso produz um evento devidamente assinado que o Zenovay consegue verificar.

Etapa 1: criar um app REST API no PayPal — e habilitar o recurso Webhooks

⚠️ Habilite o recurso Webhooks no seu app.

Novos apps REST API do PayPal vêm por padrão com "Accept payments only". O seu app precisa ter o recurso Webhooks habilitado para poder criar e verificar webhooks. Essa é uma configuração única de 30 segundos.

  1. Faça login no PayPal Developer

    Acesse developer.paypal.com e faça login com a sua conta empresarial do PayPal. É gratuito; leva cerca de um minuto.

  2. Abra Apps & Credentials

    No painel, clique em Apps & Credentials. Alterne para Sandbox para testes ou Live para produção.

  3. Crie um novo app

    Clique em Create App. Dê um nome como "Zenovay Analytics". Escolha Merchant como tipo de app. Clique em Create App.

  4. Copie o Client ID e o Secret

    O PayPal mostra o seu Client ID (uma string alfanumérica longa) e o Secret (clique em Show para revelar). Mantenha essa aba aberta — você vai colar esses valores no Zenovay na Etapa 3.

  5. Marque a caixa do recurso Webhooks

    Ainda na página de configurações do seu app, role até a seção Features (às vezes chamada de App settings). Você verá caixas de seleção como Accept payments, Vault, Payouts, Subscriptions, Log in with PayPal e Webhooks.

    Marque a caixa Webhooks e clique em Save Changes no final da página.

    Não é preciso regerar o seu Client Secret — a nova permissão se aplica imediatamente a novos tokens OAuth.

Etapa 2: criar o webhook no PayPal e copiar seu Webhook ID

Abra as configurações do seu site no Zenovay e vá para a aba Revenue (sob a seção Analytics), depois clique no card do PayPal. O formulário mostra uma URL de webhook copiável que já inclui o ID do seu site — copie-a e registre o webhook do lado do PayPal.

  1. Copie sua URL de webhook do Zenovay

    No card do PayPal no Zenovay, copie a URL do webhook mostrada no topo do formulário. Ela se parece com:

    https://api.zenovay.com/api/webhooks/paypal/YOUR_WEBSITE_ID

    A URL já está preenchida com o ID do seu site — você não precisa construí-la você mesmo.

  2. Adicione o webhook no PayPal

    De volta no PayPal Developer, dentro das configurações do seu app, role até Sandbox Webhooks (ou Live Webhooks). Clique em Add Webhook e cole a URL que você copiou.

  3. Inscreva-se nos eventos certos

    Marque, no mínimo:

    • Payment capture completed
    • Payment capture refunded
    • Checkout order approved (opcional; registrado para observabilidade)

    Clique em Save. O PayPal gera um Webhook ID — guarde-o para a Etapa 3.

Etapa 3: conectar no Zenovay

Ainda no card do PayPal na aba Revenue das suas configurações de site:

  1. Cole as suas três credenciais

    • Client ID — da Etapa 1
    • Client Secret (este é o campo API Key) — da Etapa 1
    • Webhook ID — o ID que o PayPal gerou na Etapa 2 (obrigatório)

  2. Escolha Sandbox ou Live

    Use o mesmo ambiente que você configurou na Etapa 1. O Sandbox usa api-m.sandbox.paypal.com; o Live usa api-m.paypal.com. Misturar os modos fará a verificação de assinatura falhar.

  3. Clique em Salvar

    O Zenovay valida as suas credenciais buscando um token de acesso OAuth2 e, em seguida, verifica o Webhook ID contra o PayPal. O card muda para Conectado.

Etapa 4: marque os pedidos com o ID do visitante (recomendado)

Para que a atribução pagamento-para-fonte-de-tráfego funcione com a maior precisão possível, defina o ID anônimo do Zenovay do visitante como custom_id ao criar o pedido do PayPal no seu servidor:

// Exemplo em Node.js usando @paypal/paypal-server-sdk
const visitorId = req.cookies['zv_visitor_id']; // ou como seu cliente o passa

await paypalClient.ordersCreate({
  body: {
    intent: 'CAPTURE',
    purchase_units: [{
      amount: { currency_code: 'USD', value: '42.00' },
      custom_id: visitorId, // ← UUID do visitante do Zenovay vai aqui
    }],
  },
});

Quando a captura é concluída, o Zenovay lê purchase_units[0].custom_id e une o pagamento à sessão do visitante — incluindo a fonte, a campanha e as páginas que ele visitou antes de pagar.

Se você não definir o custom_id, a atribução ainda funciona via o e-mail do pagador, mas com menos precisão (só corresponde se o visitante tiver se identificado anteriormente com o mesmo e-mail).

Como funciona a atribuição

O Zenovay atribui cada pagamento a uma fonte de tráfego e permite que você alterne entre vários modelos de atribuição na aba Revenue:

  • Last Touch (padrão) — 100% do crédito vai para o último canal antes da conversão. Bom para medir o que fecha negócios.
  • First Touch — 100% do crédito vai para o canal que primeiro trouxe o visitante. Bom para medir o que impulsiona a descoberta.
  • Linear — divide o crédito uniformemente entre todos os canais que o visitante usou.
  • Position-Based — 40% para o primeiro canal, 40% para o último, os 20% restantes distribuídos entre tudo no meio.
  • Time-Decay — mais crédito para canais mais próximos à conversão, em uma meia-vida de 7 dias.

Você escolhe o modelo na aba Revenue; a divisão é recalculada para o modelo que você escolhe.

Etapa 5: testando no Sandbox — use um checkout real, não o Simulator

Não use o Webhooks Simulator do PayPal para testar. Por design, eventos do simulador não podem ter a assinatura verificada (o PayPal documenta isso) — eles sempre falharão na verificação do Zenovay. Use um checkout real no Sandbox, conforme descrito abaixo.

A forma correta de verificar a sua integração no Sandbox:

  1. PayPal Developer Dashboard → Sandbox → Accounts. Você verá uma conta sandbox Personal (buyer) padrão com um e-mail e senha falsos — essas são as credenciais do comprador de teste.
  2. A partir da sua aplicação ou do PayPal SDK, crie um pedido de sandbox apontando para o seu client_id de sandbox (defina purchase_units[0].custom_id = visitorId se quiser a melhor atribuição — veja a Etapa 4 acima).
  3. Conclua o checkout com a conta de comprador sandbox da Etapa 1.
  4. Em até cerca de 10 segundos, o PayPal envia um webhook PAYMENT.CAPTURE.COMPLETED real e assinado para o Zenovay. Verifique se ele chegou abrindo a aba Revenue no seu dashboard de site — a captura deve aparecer com o e-mail do comprador sandbox e o valor.

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

  • Confira o badge de Status de verificação no card do PayPal nas suas configurações de Revenue — ele mostra o erro mais recente.
  • Confirme se o modo Sandbox vs Live está coerente: um webhook de Sandbox disparado contra uma integração Live (ou vice-versa) falhará na verificação de assinatura.
  • Confirme se o webhook ainda está registrado no PayPal: PayPal Dashboard → seu app → Webhooks. Se ele tiver sido excluído, re-adicione-o e cole o novo Webhook ID devolta no Zenovay.

Mudando do Sandbox para o Live

Quando estiver pronto para produção:

  1. No PayPal Developer, crie um app REST API Live e um Webhook Live (Etapa 1 + Etapa 2 novamente, mas na aba Live — o webhook Live obtém seu próprio Webhook ID).
  2. No Zenovay, abra o card do PayPal, cole as credenciais Live e o Webhook ID Live, mude o toggle para Live e clique em Salvar.

O PayPal envia os eventos para o ambiente que corresponde ao Webhook ID registrado, então mantenha as credenciais e o Webhook ID do mesmo ambiente juntos.

Desconectar

Abra as configurações do seu site → aba Revenue → clique no card do PayPal → Desconectar.

Por padrão, desconectar apenas remove suas credenciais do PayPal. Seus registros de pagamentos existentes, histórico de atribuição e dados do painel de Receita 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 os dados históricos do PayPal

A caixa de diálogo de desconexão inclui uma caixa de seleção: "Também excluir permanentemente N registros do PayPal (R$ X no total)". Marque-a apenas se quiser começar do zero — por exemplo, descomissionando uma integração de teste ou fazendo limpeza de privacidade.

Quando marcada, o Zenovay irá:

  • excluir todas as linhas payment_events do PayPal para este site
  • excluir todas as linhas payments do PayPal para este site
  • limpar o campo paypal_customer_id em todos os usuários identificados (o registro de usuário em si é preservado — ele mantém seu Stripe ID, etc.)

A exclusão ocorre em uma única transação — se qualquer etapa falhar, as três são revertidas, então você nunca fica em um estado meio-excluído. A ação é irreversível.

Não se esqueça de remover o webhook no lado do PayPal

Desconectar no Zenovay apenas faz o Zenovay parar de aceitar eventos. O PayPal continuará disparando o webhook em nosso endpoint até você removê-lo no seu PayPal Developer Dashboard:

  1. Abra https://developer.paypal.com/dashboard/applications/
  2. Clique no seu app PayPal REST API.
  3. Abra a seção Webhooks.
  4. Encontre o webhook apontando para https://api.zenovay.com/api/webhooks/paypal/{your-website-id} e Remova.

Até você removê-lo no lado do PayPal, nosso endpoint responderá 410 Gone a cada entrega. O PayPal abandona retentativas após 410 — então é majoritariamente cosmético, mas é boa higiene e evita que o webhook lote os próprios logs de retentativa do PayPal.

Limitações

  • Uma conta PayPal por site Zenovay. Se você aceita pagamentos por meio de várias contas PayPal, configure cada uma no seu próprio site Zenovay.
  • A conexão é apenas entrada manual. Não há redirecionamento OAuth "Log in with PayPal" — você cola o Client ID, Client Secret e Webhook ID diretamente.

Solução de problemas

"Verification failed" em um webhook de teste real

Geralmente é uma incompatibilidade entre Sandbox e Live — um webhook disparado por sandbox.paypal.com contra credenciais marcadas como Live (ou vice-versa) vai falhar na verificação de assinatura. Confira se o toggle no card do PayPal corresponde ao ambiente das suas credenciais.

Se você usou o Webhooks Simulator do PayPal, isso é uma limitação conhecida — eventos do simulador não podem ter a assinatura verificada por design (o PayPal vincula a assinatura a um literal WEBHOOK_ID de placeholder, não ao seu Webhook ID real). Sempre teste com um checkout real no Sandbox.

« NOT_AUTHORIZED » / erro 403

Isso significa geralmente que o recurso Webhooks não está habilitado no seu app REST API do PayPal, ou você está usando um conta sandbox Personal onde os webhooks requerem um conta sandbox Business.

Solução:

  1. Abra https://developer.paypal.com/dashboard/applications e clique no seu app.
  2. Confirme que você está na aba certa (Sandbox ou Live) — elas têm configurações separadas.
  3. Role até a seção Features (logo abaixo do bloco do Client ID / Secret).
  4. Marque a caixa Webhooks.
  5. Clique em Save Changes no final da página.
  6. Se estiver no Sandbox, confirme que está usando um conta sandbox Business, não uma Personal.

Não é preciso regerar o Client Secret. A nova permissão se aplica imediatamente a novos tokens OAuth.

Atingiu o limite de 10 webhooks no seu app do PayPal

O PayPal limita cada app REST API a 10 webhooks. Se você registrou o Zenovay várias vezes (por exemplo, em vários sites do Zenovay), pode acabar atingindo esse limite. Você pode excluir webhooks não utilizados em https://developer.paypal.com/dashboard/applications, ou adicionar um novo webhook e colar seu ID no site Zenovay relevante.

Leitura relacionada

Artigos relacionados

  1. Como integro o Paddle para rastreamento de receita?

    Conecte o Zenovay à sua conta do Paddle Billing (v2) para atribuir receita de volta a fontes de tráfego, campanhas e visitantes individuais. Configuração com Sandbox primeiro, uma única chave API e verificação de assinatura de webhook.

  2. Como integro o Stripe para rastreamento de receita?

    Conecte o Zenovay à sua conta Stripe para atribuir receita às fontes de tráfego, campanhas e visitantes individuais. Cole uma chave API restrita do Stripe e Zenovay faz o resto.

  3. Webhooks

    Configure webhooks de saída para receber notificações em tempo real do Zenovay quando ocorrerem eventos da plataforma e aprenda como o Zenovay processa internamente os webhooks de pagamento de entrada.

Este artigo foi útil?