Integrar Stripe

Conectar o Stripe à Repass não atribui vendas sozinho. São duas etapas:

Receber o fato financeiro — webhook do Stripe → ingestão (assinatura criada, cobrança, estorno, cancelamento).
Saber o afiliado — colocar o id do clique (repass_cid = clk_…) na metadata do checkout/assinatura, ou usar fallbacks (visitante, e-mail identificado, cupom).

Sem o passo 2, o webhook responde 200 com outcome: unmatched e nada é gravado.

O passo que a maioria esquece é a metadata. Sem repass_cid (prefixo clk_) no objeto certo do Stripe, a venda chega na Repass mas não casa com nenhum afiliado.

Pré-requisitos

Antes do primeiro webhook útil:

Programa ativo com regra de comissão vigente
Afiliado aprovado com link rastreável
(Recomendado) tracker client-side no seu site, para capturar repass_cid / repass_vid da URL após o redirect /t/{token}

Passo 1: conectar o Stripe

No painel da Repass, em Configurações → Integrações:

Conectar Stripe (OAuth) — configura webhook e credenciais em um passo, ou
Configurar manualmente — aponte um webhook no Stripe para:

https://api.userepass.com/ingest/stripe/{organizationId}

Eventos a assinar:

invoice.paid (ou invoice.payment_succeeded)
checkout.session.completed
charge.refunded
customer.subscription.deleted
charge.dispute.created (só tem efeito se você gravar também a secret key sk_…)

Cole o signing secret (whsec_…) no painel. A secret key da API (sk_…) é opcional: habilita chargebacks, taxas de gateway e resolução de cupom Stripe → atribuição por cupom.

Só BRL é suportado. Eventos em outra moeda são ignorados (unsupported_currency).

Detalhes de autenticação HMAC, desfechos e configuração: Ingestão.

Passo 2: capturar o clique no seu site

Quando o visitante clica no link do afiliado (GET /t/{token}), a Repass redireciona para o seu destino com repass_cid e repass_vid na query. Persista esses valores até o checkout (a tag /t.js faz isso automaticamente). No signup/login, associe o visitante ao e-mail (Repass.identify(...)) para atribuição cross-device.

Passo 3: injetar a metadata no Stripe (obrigatório para atribuição explícita)

A Repass lê dois campos da metadata:

Campo	Significado	Prefixo
`repass_cid`	Id do clique (`clickId`)	deve começar com `clk_`
`repass_pid`	Id do programa (opcional)	deve começar com `prog_`

Valor sem o prefixo é descartado em silêncio.

Assinatura (Checkout `mode: subscription`)

A conversão canônica vem de invoice.paid com billing_reason = subscription_create. O checkout.session.completed em modo subscription é ignorado de propósito (evita duplicar). Coloque a metadata na subscription:

const clickId = Repass.getClickId(); // ou o valor que você persistiu

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: "price_...", quantity: 1 }],
  subscription_data: {
    metadata: {
      repass_cid: clickId, // clk_...
      // repass_pid: "prog_...", // se a org tem mais de um programa
    },
  },
});

O tradutor procura repass_cid / repass_pid na metadata da invoice, do line item e do subscription_details (incluindo o layout da API Stripe 2025+).

Compra avulsa (Checkout `mode: payment`)

Coloque a metadata na session:

const session = await stripe.checkout.sessions.create({
  mode: "payment",
  metadata: {
    repass_cid: clickId,
  },
  line_items: [{ price: "price_...", quantity: 1 }],
  // ...
});

Payment Intents / Subscriptions via API

Mesma ideia: grave repass_cid (e opcionalmente repass_pid) na metadata do objeto que o webhook traduz.

O que cada evento vira

Evento Stripe	Vira na Repass
`invoice.paid` (`subscription_create`)	Conversão `subscription_created`
`invoice.paid` (ciclo / update / threshold)	Cobrança (`charge`) do ciclo 2+
`checkout.session.completed` (`mode: payment`)	Conversão `one_time_purchase`
`checkout.session.completed` (`mode: subscription`)	Ignorado (usa o invoice)
`charge.refunded`	Refund / clawback
`charge.dispute.created` + `sk_`	Chargeback
`customer.subscription.deleted`	Cancelamento (anula comissões em hold)

Depois da primeira conversão atribuída, renovações e estornos amarram pelo customerId do Stripe — você não precisa reenviar repass_cid em cada ciclo.

Desfechos (`outcome`)

O webhook responde 200 sempre que a assinatura é válida. O corpo traz o desfecho real:

Outcome	Significado
`processed`	Conversão/comissão/refund aplicado
`replayed`	Mesmo fato financeiro já processado (`sourceEventId`)
`unmatched`	Sem afiliado (`no_attribution`) — quase sempre falta `repass_cid`
`skipped`	Regra de negócio impediu o efeito
`ignored`	Evento não mapeado ou moeda ≠ BRL

Fallbacks sem metadata

Se o cliente passou por um link rastreado e você identificou o e-mail (/track/identify), a Repass ainda pode atribuir pela cascata visitorId → emailHash → fingerprint. A metadata continua sendo o caminho explícito e mais confiável, especialmente quando o checkout não herda cookies do site. Cupons sincronizados com o Stripe também atribuem quando a secret key está configurada (promotion code → couponCode).

Alternativas ao webhook Stripe

Caminho	Quando usar
`POST /conversions`	Você controla o momento e manda `clickId` direto
`POST /ingest/custom`	Gateway que não é Stripe
Tracker client-side	Complemento; confirme com S2S/webhook e o mesmo `sourceEventId`

Próximos passos

Ingestão

Contrato normalizado, HMAC e configuração do webhook.

Tracker client-side

Capturar repass_cid no browser sem backend.

Conversões S2S

Enviar conversões pelo seu backend.

Refund e clawback

Como estornos viram comissões negativas.

Introdução

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Integrar Stripe

Pré-requisitos

Passo 1: conectar o Stripe

Passo 2: capturar o clique no seu site

Passo 3: injetar a metadata no Stripe (obrigatório para atribuição explícita)

Assinatura (Checkout `mode: subscription`)

Compra avulsa (Checkout `mode: payment`)

Payment Intents / Subscriptions via API

O que cada evento vira

Desfechos (`outcome`)

Fallbacks sem metadata

Alternativas ao webhook Stripe

Próximos passos

Ingestão

Tracker client-side

Conversões S2S

Refund e clawback

​Pré-requisitos

​Passo 1: conectar o Stripe

​Passo 2: capturar o clique no seu site

​Passo 3: injetar a metadata no Stripe (obrigatório para atribuição explícita)

​Assinatura (Checkout mode: subscription)

​Compra avulsa (Checkout mode: payment)

​Payment Intents / Subscriptions via API

​O que cada evento vira

​Desfechos (outcome)

​Fallbacks sem metadata

​Alternativas ao webhook Stripe

​Próximos passos

Ingestão

Tracker client-side

Conversões S2S

Refund e clawback

Pré-requisitos

Passo 1: conectar o Stripe

Passo 2: capturar o clique no seu site

Passo 3: injetar a metadata no Stripe (obrigatório para atribuição explícita)

Assinatura (Checkout `mode: subscription`)

Compra avulsa (Checkout `mode: payment`)

Payment Intents / Subscriptions via API

O que cada evento vira

Desfechos (`outcome`)

Fallbacks sem metadata

Alternativas ao webhook Stripe

Próximos passos