Skip to main content
Se o seu produto usa Stripe para cobrar clientes, conectar sua conta no Retuno é o caminho mais rápido para começar a recuperar receita. A integração lê automaticamente eventos relevantes da sua conta Stripe (cancelamentos, falhas de cobrança, disputas) e dispara o agente sem você precisar escrever nenhum código.
Esta integração é somente leitura — o Retuno não cobra clientes, não cria assinaturas e não modifica nada na sua Stripe. Apenas observa os eventos que já acontecem na sua conta.

​
Funciona junto com o Webhook receiver

A integração com a Stripe não substitui o Webhook receiver — as duas coexistem e se complementam. Use cada uma para o que ela faz melhor:
IntegraçãoSinais que cobre
StripeCancelamento confirmado, cancelamento agendado para fim do ciclo, falha de pagamento, disputa.
Webhook receiverSinais que só o seu produto enxerga: inatividade, queda de uso, visita à página de cancelamento, eventos de tracking, e qualquer outro gatilho específico do seu negócio.
Para clientes Stripe, o cenário ideal é usar as duas: a Stripe cuida automaticamente dos sinais de billing, e o webhook receiver complementa com sinais comportamentais que aumentam a precisão preditiva do agente.
Identidade do cliente quando você usa as duas integrações. A Stripe identifica clientes por cus_xxx. O Webhook receiver identifica pelo customer.external_id que você envia. Para que o Retuno consolide os sinais no mesmo cliente, envie o Stripe customer ID como external_id nos eventos do webhook receiver. Se você usar IDs diferentes (ex.: ID interno do seu sistema), o Retuno tratará como dois clientes distintos.

​
Pré-requisitos

  • Conta Stripe ativa (modo Live ou Test).
  • Permissão de admin no painel do Retuno.
  • Acesso ao Stripe Dashboard com permissão para criar restricted keys e webhook endpoints.

​
Configuração

A configuração leva cerca de 5 minutos e tem três etapas: criar uma chave restrita na Stripe, criar um endpoint de webhook na Stripe e conectar tudo no Retuno.
1

1. Crie uma chave restrita na Stripe

No Stripe Dashboard, acesse Developers → API keys e clique em Create restricted key.Configure as permissões mínimas:
  • Customers: Read
  • Subscriptions: Read
Dê um nome descritivo (ex.: “Retuno”) e crie. Copie a chave (rk_live_... ou sk_live_...) e guarde — você vai precisar dela no passo 3.
A documentação oficial sobre restricted keys está em Stripe Docs — Restricted API keys.
2

2. Crie um webhook endpoint na Stripe

No Stripe Dashboard, acesse Developers → Webhooks e clique em Add endpoint.No campo Endpoint URL, cole a URL exibida pelo Retuno no passo de Stripe do onboarding (ela é única para cada organização).Em Events to send, marque:
  • customer.subscription.deleted — cancelamento confirmado
  • customer.subscription.updated — captura cancelamentos agendados para fim do ciclo
  • invoice.payment_failed — falha de pagamento
  • charge.dispute.created — disputa/chargeback
Crie o endpoint. Na tela do endpoint criado, revele e copie o Signing secret (whsec_...). Você vai precisar dele no próximo passo.
Mais detalhes sobre webhooks da Stripe em Stripe Docs — Webhooks.
3

3. Conecte no Retuno

No painel do Retuno, no passo de Webhook do onboarding (ou em Configurações → Stripe se já passou pelo onboarding), escolha a opção Stripe ou Stripe + Webhook receiver.Cole:
  • A chave restrita copiada no passo 1.
  • O signing secret copiado no passo 2.
Clique em Conectar. O Retuno valida a chave imediatamente e mostra a quantidade de clientes detectados na sua conta. Se aparecer erro de chave inválida, revise as permissões da restricted key.

​
Como o telefone do cliente é resolvido

O agente conversa por WhatsApp, então cada cliente Stripe precisa ter um telefone resolvível para que uma conversa seja iniciada. O Retuno tenta encontrar o telefone na seguinte ordem:
  1. Mapeamento manual via CSV. Se você fez upload de um CSV mapeando IDs Stripe para telefones, ele tem prioridade. Útil quando você guarda telefones em outro sistema (CRM, planilha) e não na Stripe.
  2. Campo phone do Customer Stripe. Se o customer.phone na Stripe está preenchido em formato internacional (ex.: +5511999999999), é usado.
  3. Metadata do Customer. Se você guarda o telefone em customer.metadata.phone, ele é usado como último recurso.
Clientes sem telefone resolvível por nenhuma dessas vias não geram conversa — o evento é registrado mas o agente não é acionado. Garanta que pelo menos uma das três fontes esteja disponível.

​
Upload do CSV de mapeamento

Em Configurações → Stripe → Mapeamento de telefones, faça upload de um CSV com este formato: 
stripe_customer_id,phone
cus_PaB3xK2eXaMpLe,+5511999999999
cus_QcD4yL3fAnOtHr,+5511988888888
Telefones devem estar em formato E.164 (com código do país). Reenviar um CSV atualiza os mapeamentos existentes.

​
O que acontece depois de conectar

Assim que a conexão é estabelecida:
  • Histórico recente é importado. O Retuno carrega os eventos relevantes dos últimos 90 dias da sua conta Stripe e os usa para análise e atribuição. Esse histórico não dispara conversas — eventos antigos servem apenas para contexto e métricas.
  • Eventos novos disparam conversas em tempo real, conforme os Guardrails que você configurou.
  • Cancelamentos agendados (cliente que clicou “cancelar ao final do ciclo”) disparam uma conversa preventiva, dando ao agente tempo para reverter antes do fim do período.
  • Disputas (chargebacks) geram apenas um alerta interno, não uma conversa. Disputas são casos sensíveis e devem ser tratadas pelo seu time financeiro/operacional.
  • Reconciliação automática roda diariamente como rede de segurança: se algum webhook não chegou (queda de rede, instabilidade), o Retuno detecta a lacuna e processa os eventos perdidos sem ação sua.

​
Impacto na atribuição de receita

Para organizações com Stripe conectada, a Atribuição de receita usa o estado real da assinatura na Stripe como fonte da verdade — em vez de inferir a partir de eventos. Isso significa atribuição mais precisa, sem depender de você enviar eventos de subscription.renewed ou similar pelo webhook receiver.

​
Troubleshooting

Conectei mas as conversas não aparecem. Confira que os clientes Stripe têm telefone resolvível (CSV, customer.phone ou customer.metadata.phone). Sem telefone, o evento é registrado mas não dispara conversa. A Stripe Dashboard mostra erros 401 ou 403 no webhook endpoint. O signing secret pode estar diferente do que está salvo no Retuno. Reconecte a Stripe no painel colando o secret atualizado do Stripe Dashboard. Quero desconectar a Stripe. Em Configurações → Stripe, clique em Desconectar. Os eventos já processados continuam armazenados para fins de histórico e auditoria, mas novos eventos da Stripe deixam de chegar ao Retuno. Você pode reconectar a qualquer momento. Recebi uma disputa e esperava uma conversa. Disputas geram apenas alerta interno por design — são casos sensíveis (chargeback, fraude) que pedem ação do time financeiro, não do agente conversacional.

​
Boas práticas

  • Use restricted keys, não chaves padrão. Limite as permissões a apenas leitura de Customers e Subscriptions.
  • Use o mesmo identificador nos dois canais. Se você também usa o webhook receiver, envie o cus_xxx da Stripe como customer.external_id para consolidar os sinais.
  • Mantenha telefones atualizados. Se telefones mudam de origem (saíram do CRM, entraram na Stripe), reflita isso no CSV ou na própria Stripe — o Retuno usa o que estiver disponível no momento do evento.
  • Não recrie o webhook endpoint na Stripe sem reconectar. Se você apagar e recriar, o signing secret muda; reconecte no Retuno com o novo secret.