Skip to main content

Visão Geral

A integração com Stripe cria conversões automaticamente quando um pagamento é aprovado no Stripe. Você não precisa chamar trackConversion() manualmente - tudo é feito via webhook.
Pré-requisito: A SDK JavaScript deve estar instalada no seu site! Ela é responsável por salvar o cookie com o código do afiliado. Esta integração Stripe é complementar à SDK.
Quando usar:
  • Você usa Stripe para processar pagamentos
  • Quer automação total de conversões
  • Processa assinaturas recorrentes ou pagamentos únicos
  • Já tem a SDK instalada

Como Funciona

  1. SDK salva cookie: Cliente acessa com ?ref=CODIGO, SDK salva no cookie
  2. Metadata no checkout: Seu backend lê o cookie e passa para o Stripe
  3. Cliente finaliza compra no Stripe
  4. Stripe aprova o pagamento
  5. Stripe envia webhook com o código do afiliado
  6. Conversão é criada automaticamente
Papel da SDK: Ela salva o código do afiliado em um cookie que dura 30 dias. Seu backend lê esse cookie e passa para o Stripe via metadata.

Configuração

Passo 1: Ative a Integração no Dashboard

  1. Vá em “Configurações”“Integrações”
  2. Encontre o card do Stripe
  3. Clique em “Ativar”
  4. Anote a URL do Webhook (você vai precisar)
A URL será algo como:

Passo 2: Crie o Webhook no Stripe

  1. Acesse o Dashboard do Stripe
  2. Clique em “Add endpoint”
  3. Cole a URL do webhook copiada no passo anterior
  4. Em “Events to send”, selecione:
    • checkout.session.completed
    • payment_intent.succeeded (opcional, para redundância)
  5. Clique em “Add endpoint”
  6. Copie o Signing Secret (começa com whsec_...)
Guarde o Signing Secret em local seguro! Ele é necessário para validar os webhooks.

Passo 3: Configure o Signing Secret

  1. Volte para o dashboard do Affiliatus
  2. Em “Configurações”“Integrações”Stripe
  3. Cole o Signing Secret no campo correspondente
  4. Clique em “Salvar”
O Signing Secret garante que apenas webhooks legítimos do Stripe sejam aceitos.

Enviando Código do Afiliado

Existem 2 formas de informar ao Stripe qual afiliado trouxe a venda:

Método 1: Via Metadata (Recomendado)

Adicione o código do afiliado no metadata da sessão de checkout:
O código pode vir de um cookie, query string (?ref=JOAO1) ou campo no formulário.

Método 2: Via Cupom de Desconto

Se o afiliado tem um cupom exclusivo no Stripe:
Neste caso, você precisa mapear o cupom ao afiliado no dashboard:
  1. Vá em “Configurações”“Mapeamento de Cupons”
  2. Associe o cupom JOAO1 ao afiliado correspondente

Exemplos de Implementação

Next.js/React

Componente React:

Node.js (Express)


PHP (Laravel)


Python (Django)


Testando a Integração

1. Teste com Stripe Test Mode

  1. Use as chaves de teste do Stripe
  2. Crie uma checkout session com metadata.affiliate_code
  3. Use o cartão de teste: 4242 4242 4242 4242
  4. Complete o pagamento
  5. Verifique se a conversão apareceu no dashboard

2. Use o Stripe CLI para Simular Webhooks

3. Verifique os Logs

No dashboard do Stripe:
  1. Vá em “Developers”“Webhooks”
  2. Clique no seu webhook
  3. Veja a lista de eventos enviados
  4. Verifique se retornou status 200 OK

Solução de Problemas

Webhook retorna erro 401 ou 403

Causa: Signing Secret incorreto ou integração não ativada. Solução:
  1. Verifique se a integração está ativa no dashboard
  2. Confirme que o Signing Secret está correto
  3. Tente reativar a integração

Conversão não é criada

Possíveis causas:
  1. Metadata não enviado
    • Verifique se metadata.affiliate_code está sendo passado
    • Confirme o valor no evento do Stripe
  2. Código de afiliado inválido
    • O código deve corresponder a um afiliado ativo
    • Verifique em “Afiliados” se o código existe
  3. Webhook não configurado
    • Confirme que o webhook está ativo no Stripe
    • Verifique se o evento checkout.session.completed está selecionado
  4. Evento duplicado
    • O sistema ignora eventos já processados
    • Cada payment_intent só gera uma conversão

Valor da conversão está errado

O valor é capturado diretamente do Stripe em centavos e convertido para reais. Exemplo:
  • Stripe: amount_total: 9900 (centavos)
  • Conversão: order_value: 99.00 (reais)
Se o valor estiver incorreto, verifique o amount_total no evento do Stripe.

Configurações Avançadas

Permitir Metadata e/ou Cupom

No dashboard, em “Integrações”“Stripe”, você pode configurar:
  • Permitir Metadata: Aceita metadata.affiliate_code
  • Permitir Cupom: Aceita cupons mapeados
Recomendamos ativar ambos para máxima flexibilidade.

Mapeamento de Cupons

Se você usa cupons de desconto como identificadores de afiliados:
  1. Vá em “Configurações”“Mapeamento de Cupons”
  2. Clique em “Adicionar Mapeamento”
  3. Selecione o cupom do Stripe
  4. Associe ao afiliado correspondente
Exemplo:
  • Cupom: DESCONTO10JOAO
  • Afiliado: João Silva (código JOAO1)

Boas Práticas

Faça

  • Sempre teste em Test Mode primeiro
  • Use metadata ao invés de cupons (mais confiável)
  • Configure o Signing Secret corretamente
  • Monitore os logs de webhook no Stripe
  • Mantenha as chaves de API seguras

Não Faça

  • Não exponha chaves secretas no frontend
  • Não desative o webhook sem avisar os afiliados
  • Não modifique o metadata após criar a sessão
  • Não use cupons genéricos para múltiplos afiliados

Próximos Passos

Aprovar conversões

Aprenda a aprovar conversões automáticas

Integração Woovi

Automatize conversões via PIX

SDK JavaScript

Rastreamento manual via JavaScript

Dashboard

Acompanhe métricas em tempo real

Precisa de Ajuda?

Não diretamente no momento. Use metadata no checkout da conta conectada e processe via API.
Sim! Funciona tanto com mode: 'subscription' quanto mode: 'payment'.
A conversão permanece no sistema. Você pode rejeitá-la manualmente se necessário.
Sim! A SDK é obrigatória para salvar o código do afiliado no cookie. Sem ela, o webhook do Stripe não terá como saber qual afiliado trouxe a venda.
Dúvidas? Entre em contato pelo suporte ou consulte a documentação do Stripe.