Voltar para documentação
Integrações

Integração Stripe

Conecte sua conta Stripe ao Synchro Hub para receber vendas em tempo real e consolidar métricas no dashboard.

Visão geral

Ao integrar o Stripe, o Synchro Hub passa a:

  • Receber webhooks de pagamentos confirmados, reembolsos, disputas (chargebacks) e renovações de assinatura — registrados automaticamente, sem configuração manual no painel Stripe.
  • Preservar a moeda original de cada venda (BRL, USD, EUR, etc.) — sem conversão de câmbio automática.

Tempo estimado: 5 minutos. O que você vai precisar:

  • Conta Stripe ativa em produção (chaves de teste só funcionam no Synchro de dev/test).
  • Permissão de administrador ou desenvolvedor na sua conta Stripe (para gerar a Secret Key).
  • Workspace já criado no Synchro Hub.

Eventos cobertos:

  • Pagamentos avulsos confirmados (payment_intent.succeeded)
  • Reembolsos (charge.refunded)
  • Chargebacks/disputas abertas (charge.dispute.created)
  • Disputas perdidas (charge.dispute.closed com status lost)
  • Renovações de assinatura / faturas pagas (invoice.paid)

Eventos como payment_intent.payment_failed, customer.* e falhas em geral não são ingeridos — não influenciam KPIs financeiros.

Pré-requisitos

  • Estar logado no Synchro Hub com um workspace selecionado.
  • Ter acesso ao Stripe Dashboard como admin/desenvolvedor.

Passo 1 — Gerar uma chave de API

Você tem duas opções. Recomendamos a Restricted Key pelo princípio do menor privilégio (limita o que o Synchro pode fazer na sua conta Stripe).

Opção A — Restricted Key (recomendado)

  1. Acesse Stripe Dashboard → Developers → API keys.
  2. Clique em Create restricted key.
  3. Dê um nome descritivo (ex.: “Synchro - Webhook Integration”).
  4. Configure as permissões mínimas:
    • Webhook Endpoints → Write
    • Account (Core resources) → Read
    • PaymentIntents (Core resources) → Read (necessário para resolver e-mail do cliente quando o checkout não envia receipt_email)
    • Customers (Core resources) → Read (idem — usado na expansão do PaymentIntent)
  5. Clique em Create key e copie o valor (formato rk_live_...).

Opção B — Standard Secret Key

  1. Acesse Stripe Dashboard → Developers → API keys.
  2. Na seção Standard keys, clique em Reveal live key ao lado de “Secret key” (formato sk_live_...).
  3. Copie o valor.

Em produção, aceitamos apenas chaves de produção: sk_live_* ou rk_live_*. Chaves de teste (sk_test_*/rk_test_*) e publicáveis (pk_*) são rejeitadas.

Em ambientes de desenvolvimento (Synchro local), também aceitamos as variantes sk_test_*/rk_test_* para facilitar testes contra a conta Stripe sandbox — mas isso é exclusivo de dev/test.

Passo 2 — Criar a integração no Synchro

  1. No Beacon, vá em Configurações → Integrações → Fontes de venda.
  2. Clique em Adicionar integração e selecione Stripe.
  3. Confirme — o Synchro cria a entrada e pede a credencial.
  4. Cole sua Stripe Secret Key no campo correspondente e clique em Salvar.

O Synchro valida a chave em tempo real (chama GET /v1/account na sua conta). Se a chave for inválida, sem permissão ou de teste, você vê o erro imediatamente.

Passo 3 — Ativar o webhook

Após salvar a credencial, o Synchro registra automaticamente o webhook na sua conta Stripe via API. Você não precisa configurar nada no Dashboard Stripe.

Se quiser conferir, vá em Stripe Dashboard → Developers → Webhooks e veja o endpoint criado com descrição “Synchro Webhook”, apontando para https://api.synchro.app/v1/webhooks/ecommerce/stripe/<id>.

Verificação

Para confirmar que tudo está funcionando:

  1. Gere uma cobrança/pagamento de teste na sua conta Stripe (uso real ou um teste interno em produção).
  2. Abra Vendas no menu lateral do Synchro Hub.
  3. A venda deve aparecer em segundos após o payment_intent.succeeded.

Limitações conhecidas

  • Sem backfill automático: vendas anteriores à integração não são importadas. Apenas eventos novos passam pelo webhook.
  • Stripe Connect (split): cada destino é registrado como comissão AFFILIATE, mas e-mail/nome do destinatário ficam em branco (o Synchro não acessa contas Connect sem permissão explícita).
  • Multi-moeda sem conversão: dashboards exibem cada venda na moeda em que foi cobrada — não há FX automático.

Solução de problemas

SintomaCausa provávelSolução
”Apenas chaves de produção são aceitas”Colou sk_test_*/rk_test_* em produçãoGere sk_live_* ou rk_live_* (dev/test aceita variantes *_test_*)
“Stripe rejeitou o registro do webhook” (403 / permission)Restricted key sem permissões suficientesRecrie a rk_* com Webhook Endpoints: Write + Account: Read (Core resources)
“Stripe Secret Key inválida ou sem permissão”Chave revogada ou sem escopoGere uma nova chave Standard com escopo total
Vendas não aparecemWebhook desativado na StripeVerifique em Stripe Dashboard → Webhooks; reative ou recadastre a integração
Disputa apareceu como APPROVED depoisVocê ganhou a disputa (status=won)Esperado — Synchro só marca CHARGEDBACK em disputas perdidas

Perguntas frequentes

Posso conectar mais de uma conta Stripe? Sim — cada conta Stripe é uma integração independente no Synchro. Repita o processo com chaves diferentes.

Como funciona com Stripe Connect (split de pagamento)? Cada destino do split é registrado como comissão AFFILIATE. Os valores estão corretos, mas o nome/e-mail do destinatário fica em branco (limitação do escopo de permissões padrão).

O Synchro converte moeda automaticamente? Não. Cada venda permanece na moeda em que foi cobrada (BRL, USD, EUR, etc.).

Como desconecto a integração? No card da Stripe no Beacon, clique em Remover. O Synchro também remove o webhook registrado na Stripe via API. Revogue a chave em Stripe Dashboard → Developers → API keys se não for mais usá-la.

Suporte

Em caso de problema, abra um ticket informando:

  1. O integrationId da integração (visível em Configurações → Integrações).
  2. O event ID Stripe (evt_...) que não chegou — vê em Stripe Dashboard → Webhooks → Event deliveries.

Atribuição de ROI em PIX/Boleto (opcional — só se você usa o SynchroPixel)

Opcional. Esta seção só interessa se você usa (ou pretende usar) o SynchroPixel para rastrear o ROI dos seus anúncios server-side. Se você não usa pixel, a integração Stripe funciona normalmente — pode pular esta seção.

Por que isso é necessário

Em pagamento por cartão (síncrono), o cliente fica na sua página até o “aprovado” — o pixel client-side dispara Purchase e Meta/Google casam o evento com o clique. Bom.

Em PIX ou Boleto, o fluxo é diferente:

  1. Cliente clica em “Pagar” → vê o QR Code / linha digitável.
  2. Sai da sua página, abre o banco, paga.
  3. Minutos (ou horas) depois, a Stripe dispara payment_intent.succeeded para o Synchro.
  4. Nesse momento o navegador do cliente não existe mais — fbp/fbc/gclid se foram.

A solução é anexar o identificador do SynchroPixel ao próprio PaymentIntent, antes do cliente sair da sua página. O webhook traz esse identificador de volta e o Synchro casa a venda com a visita original — disparando CAPI server-side com todos os parâmetros corretos.

O que você vai injetar

Uma única chamada no seu checkout:

const metadata = window.synchroPixel.getCheckoutMetadata();

Retorna um objeto plano (só com chaves preenchidas) que inclui:

ChaveOrigemPara que serve
synchroSessionIdCookie 1st-party (UUID gerado pelo pixel)Casamento direto venda↔visita
fbclidURL da landing pageAtribuição Meta
gclidURL da landing pageAtribuição Google
ttclidURL da landing pageAtribuição TikTok
fbp, fbcCookies do FacebookEMQ score Meta CAPI
utmSource, utmMedium, utmCampaign, utmContent, utmTermURL da landingAtribuição de campanha

Você não precisa enviar todas — basta repassar o objeto completo. Chaves ausentes (null) já são omitidas.

Exemplo 1 — Stripe Checkout Session (back-end)

Quando você cria uma checkout.sessions.create no back-end, o navegador ainda está na sua página. Capture o metadata via fetch e envie ao endpoint que cria a sessão:

<!-- frontend -->
<button id="pay">Pagar com PIX</button>
<script>
  document.getElementById('pay').addEventListener('click', async () => {
    const metadata = window.synchroPixel?.getCheckoutMetadata() ?? {};
    const res = await fetch('/api/create-checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ metadata }),
    });
    const { url } = await res.json();
    window.location = url;
  });
</script>
// backend Node (Stripe SDK)
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

app.post('/api/create-checkout', async (req, res) => {
  const { metadata } = req.body; // { synchroSessionId, fbclid, gclid, ... }
  const session = await stripe.checkout.sessions.create({
    mode: 'payment',
    payment_method_types: ['pix', 'boleto', 'card'],
    line_items: [{ price: 'price_XXX', quantity: 1 }],
    success_url: 'https://seu-site.com/obrigado',
    cancel_url: 'https://seu-site.com/cancelado',
    payment_intent_data: { metadata }, // ← AQUI: chega no webhook
  });
  res.json({ url: session.url });
});

A Stripe envia o objeto metadata no webhook payment_intent.succeeded (campo charge.metadata). O Synchro lê automaticamente todas as chaves canônicas.

Exemplo 2 — Stripe Payment Element (client-side)

Se você usa o Payment Element no front (sem back-end de checkout), passe o metadata no confirmPayment:

const elements = stripe.elements({ clientSecret });
const card = elements.create('payment');
card.mount('#payment-element');

document.getElementById('submit').addEventListener('click', async () => {
  const result = await stripe.confirmPayment({
    elements,
    confirmParams: {
      return_url: 'https://seu-site.com/obrigado',
      payment_method_data: {
        metadata: window.synchroPixel?.getCheckoutMetadata() ?? {},
      },
    },
  });
  if (result.error) console.error(result.error);
});

Atenção: o clientSecret precisa vir de um PaymentIntent criado no back-end. Para redundância, passe o metadata também na criação do PaymentIntent — a Stripe mescla os dois.

Como validar

  1. No Stripe Dashboard: abra a Payment ou Charge → seção Metadata → confira que synchroSessionId está lá.
  2. No Beacon: após a confirmação, abra Vendas → detalhe e veja a coluna Origem do clique. Deve mostrar “Sessão (synchroSessionId)” — o casamento direto. Em Anúncios → Atribuição, a venda aparece sob o anúncio correto.
  3. Meta Events Manager: eventos Purchase com EMQ ≥ 7 (com fbc/fbp/fbclid). Google Ads: conversões com gclid populado.

FAQ rápido

E se o cliente bloqueou o pixel via AdBlocker? window.synchroPixel fica undefined. Os exemplos acima já usam ?. — sem o pixel, o objeto vai vazio e a Stripe aceita. O Synchro cai em match por email (janela 7d) — atribuição mais fraca mas existe.

Posso adicionar campos extras ao metadata da Stripe? Sim, a Stripe aceita até 50 chaves. O Synchro só lê o vocabulário canônico — chaves desconhecidas são ignoradas (você pode usá-las para seu próprio sistema).