Como integro o Stripe para rastreamento de receita?

Conectar o Stripe permite que o Zenovay mostre 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.

A configuração acontece por site, dentro do painel de controle desse site. Há uma credencial para colar — uma chave API restrita do Stripe — e o Zenovay faz o resto do setup do webhook.

Conectar o Stripe

1. 1

   Abra as configurações de Revenue do site

   No app.zenovay.com, abra o site que deseja conectar, vá para Configurações e abra a aba Revenue. Cada conexão Stripe é mapeada para um site Zenovay.

2. 2

   Escolha Stripe

   Clique no cartão Stripe. Você verá um formulário de configuração breve.

3. 3

   Crie e cole uma chave API restrita

   Zenovay vincula diretamente para a tela "Criar chave restrita" do Stripe com as permissões de leitura que precisa (saldo, cobranças, assinaturas, clientes, intenções de pagamento, sessões de checkout, faturas) mais escrita de webhook. Crie a chave no Stripe, copie-a (começa com rk_live_… ou rk_test_…), cole-a no campo e clique em Conectar.

4. 4

   Deixe o Zenovay terminar a configuração

   Quando você salva a chave, o Zenovay a valida contra o Stripe e cria automaticamente o endpoint do webhook em sua conta Stripe, para que os pagamentos comecem a fluir sem você tocar no Stripe Dashboard. O cartão mostra Conectado com um badge verde "credenciais verificadas" assim que terminar.

Uma vez conectado, a aba Revenue do seu painel mostra gráficos de MRR, ARR, receita por visitante e receita por fonte. A receita é capturada a partir do momento em que você se conecta — Zenovay registra os pagamentos conforme o Stripe envia os eventos de webhook, não faz reimportação retroativa do histórico do Stripe.

Configurar o webhook manualmente (opcional)

O Zenovay cria o webhook do Stripe para você, portanto a maioria das pessoas nunca precisa disso. Se você preferir conectar o webhook você mesmo — por exemplo porque sua chave Stripe não inclui permissão de escrita de webhook — você pode apontar o Stripe para o receptor Zenovay e colar de volta o segredo de assinatura.

1. No Stripe Dashboard, vá para Developers → Webhooks → Add endpoint.
2. URL do endpoint: https://api.zenovay.com/api/webhooks/stripe/YOUR_WEBSITE_ID (seu ID de site está na URL da página do painel do seu site).
3. Selecione estes eventos:
   • checkout.session.completed
   • payment_intent.succeeded
   • invoice.paid
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
4. Salve, depois copie o segredo de assinatura do endpoint (começa com whsec_…).
5. De volta no formulário Stripe do Zenovay (aba de configurações Revenue), cole o segredo de assinatura para que o Zenovay possa verificar os eventos recebidos.

Atribuir um pagamento a um visitante

Para que a atribuição pagamento-para-fonte-de-tráfego funcione, o ID anônimo do Zenovay do visitante precisa chegar ao registro do Stripe. A forma mais simples é defini-lo como client_reference_id da sessão de checkout, ou anexá-lo como metadados no checkout:

// No seu servidor de checkout
const visitorId = req.cookies['zv_visitor_id'] // ou como seu cliente o passa
stripe.checkout.sessions.create({
  // ...
  client_reference_id: visitorId,
  metadata: { zenovay_visitor_id: visitorId }
})

Quando o pagamento é concluído, o handler de webhook do Zenovay lê o client_reference_id (ou metadata.zenovay_visitor_id / metadata.visitor_id) e une o pagamento à sessão do visitante — incluindo a fonte, a campanha e as páginas que ele visitou antes de pagar. Os pagamentos sem um ID de visitante ainda são registrados como receita, apenas sem atribuição de fonte.

Quais modelos de atribuição estão disponíveis

O Zenovay calcula vários modelos de atribuição para que você possa ver como o crédito muda dependendo de quais pontos de contato você pondera:

• Last Touch — o crédito vai para a fonte na sessão onde o pagamento aconteceu.
• First Touch — o crédito vai para a fonte de onde o visitante chegou primeiro.
• Linear — crédito dividido equitativamente entre todos os pontos de contato no caminho.
• Position-Based — pondera o primeiro e último ponto de contato mais fortemente.
• Time-Decay — pontos de contato mais próximos à conversão recebem mais crédito.

Alterne entre eles na aba Revenue para comparar como cada modelo atribui crédito.

Desconectar

Abra o cartão Stripe na aba de configurações Revenue do site e clique em Remover. Por padrão, isso apenas desconecta as credenciais — seus registros de pagamento existentes permanecem no painel durante sua janela de retenção de dados. Se você também quiser excluir os dados históricos de receita, marque a opção de exclusão em cascata na caixa de diálogo de confirmação (ela mostra exatamente quantos registros serão apagados).

Remover a integração no Zenovay não deleta o webhook no lado do Stripe, então você pode querer remover também o endpoint no seu Stripe Dashboard.

Leitura relacionada

• Visão geral de webhooks
• Rastreamento de receita de e-commerce
• Visão geral da API
• Instalando o script de rastreamento