Navegar na documentação

Stripe

OAuth (Connect) · cartão, recorrência nativa

Stripe Connect (OAuth): você autoriza uma vez e os eventos de todas as contas conectadas chegam num endpoint único. Recorrência nativa, cartão.

Client ID, chave e webhook precisam corresponder à mesma conta e ambiente. Valide a integração em ambiente de teste antes de processar vendas reais; conexão ativa não comprova atribuição ou homologação.

Conectar

Ative o Connect (Connect → Overview → Standard/OAuth) e aceite o termo de plataforma.
Settings → Connect → OAuth: copie o client_id (ca_…) e adicione o Redirect URI https://indicasaas.com/oauth/stripe/callback.
Developers → API keys: copie a Secret key (sk_live_…).
Developers → Webhooks: crie um endpoint https://indicasaas.com/webhooks/stripe, estilo Snapshot, ouvindo Connected accounts, com os eventos da tabela abaixo. Copie o signing secret (whsec_…).
Configure os 3 como secrets do Worker: STRIPE_CLIENT_ID, STRIPE_SECRET_KEY, STRIPE_CONNECT_WEBHOOK_SECRET — todos da mesma conta, no mesmo modo.
No painel → Meu SaaS → Instalação → Gateways → Stripe → Conectar → autorize.

Passe o ref no checkout

Leia a referência com AFS.getRef() e envie o valor completo, sem interpretar ou encurtar, no client_reference_id (Checkout) e/ou subscription_data.metadata.aff_ref (assinatura) ao criar a cobrança. Se retornar null, omita o campo de indicação.

const ref = AFS.getRef(); // vindo do front

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',            // ou 'payment'
  line_items: [/* ... */],
  client_reference_id: ref,        // 1ª venda
  subscription_data: {             // renovações mantêm a atribuição
    metadata: { aff_ref: ref },
  },
  // O backend determina este valor pelo cadastro do SaaS:
  metadata: { aff_new: isNewCustomer ? '1' : '0' },
});

Em assinaturas, a 1ª cobrança só semeia a atribuição; a comissão vem em cada invoice.paid — evita comissão dobrada na 1ª cobrança.

Eventos

Evento	O que faz
`checkout.session.completed`	1ª venda (one-off) ou semeia a assinatura
`invoice.paid` / `invoice.payment_succeeded`	cobrança recorrente → comissão
`charge.refunded`	reembolso → clawback
`charge.dispute.created`	chargeback → clawback
`charge.dispute.closed`	desfecho da disputa; vitória pode restaurar a parcela de comissão debitada
`customer.subscription.deleted`	cancelamento (churn)

Problemas comuns

gw_error=exchange indica falha na troca do código OAuth. Confira credenciais, conta e ambiente; o código isolado não identifica a causa.

Como a atribuição funciona Widget & SDK