RevenueCat Stripe Billing

Acompanhe comissões em assinaturas web gerenciadas pela integração Stripe Billing do RevenueCat - combinando o gerenciamento de assinaturas do RevenueCat com o processamento de pagamentos do Stripe.

Ao habilitar o rastreamento do RevenueCat Stripe Billing, você pode atribuir assinaturas web a afiliados enquanto o RevenueCat gerencia o ciclo de vida das assinaturas.

O que você pode acompanhar

Uma vez configurado, o Insert Affiliate acompanha automaticamente:

  • Assinaturas web do RevenueCat processadas via Stripe
  • Compras iniciais de assinatura
  • Renovações de assinatura
  • Todas as transações gerenciadas pelo web billing do RevenueCat

Pré-requisitos

Antes de configurar o rastreamento do Insert Affiliate, você precisa ter:

  • RevenueCat Web SDK instalado e configurado
  • RevenueCat Stripe Billing configurado e conectado à sua conta Stripe
  • Sua própria página de checkout hospedada onde o SDK do Insert Affiliate possa ser executado
  • Uma conta Stripe pronta para conectar via Stripe Connect

Importante: O Insert Affiliate exige que o seu checkout seja hospedado no seu próprio domínio. O SDK precisa ser executado na sua página para capturar a atribuição do afiliado antes das compras.

Configuração do Webhook do RevenueCat

Importante: Ao configurar o seu webhook do RevenueCat para enviar eventos ao Insert Affiliate, você deve enviar apenas eventos da App Store e da Google Play Store - não eventos do Stripe ou de Web Billing.

Como o Insert Affiliate recebe eventos do Stripe diretamente por meio do Stripe Connect (configurado na Etapa 2 abaixo), enviar eventos de webhook do RevenueCat para transações de Stripe/Web Billing resultaria em rastreamento duplicado de transações.

Para configurar o seu webhook do RevenueCat:

  1. Acesse o seu painel do RevenueCat → Project Settings → Integrations → Webhooks
  2. Ao configurar o webhook do Insert Affiliate, configure-o para enviar apenas eventos de:
    • App Store (iOS)
    • Google Play Store (Android)
  3. Não inclua eventos do Stripe ou de Web Billing nesse webhook

Isso garante uma atribuição limpa: transações móveis são rastreadas via webhooks do RevenueCat, enquanto transações web são rastreadas via Stripe Connect.

Guia de Configuração

Etapa 1: Habilitar Pagamentos Web

  1. Acesse Settings → Web Transactions
  2. Altere o Web Transaction Method de "Disabled" para "Stripe Web Payments"
  3. Clique em "Save Settings"

Etapa 2: Configurar o Stripe Connect

Antes de poder rastrear transações web, você precisa conectar a sua conta Stripe:

  1. Acesse Settings → Stripe Connect
  2. Clique em "Connect with Stripe"
  3. Conclua o processo de onboarding do Stripe:
    • Faça login na sua conta Stripe existente (a mesma conectada ao RevenueCat)
    • Forneça as informações comerciais necessárias
    • Envie os documentos de verificação (se solicitado)
  4. Você será redirecionado de volta ao Insert Affiliate ao concluir

Indicadores de status:

  • Active: Sua conta Stripe está totalmente conectada e pronta
  • Restricted: Informações adicionais necessárias - clique em "Continue Onboarding"
  • Pending: Documentos em análise (normalmente de 1 a 2 dias úteis)

✅ Uma vez que a sua conta Stripe esteja conectada, o Insert Affiliate receberá automaticamente todos os eventos do Stripe das suas transações do RevenueCat.

Implementação: Passando Códigos de Afiliado

Etapa 1: Instalar o SDK do Insert Affiliate

Adicione o SDK do Insert Affiliate à sua página de checkout web:

npm install insert-affiliate-js-sdk

Etapa 2: Inicializar o SDK

Inicialize o SDK na sua página de checkout antes que os usuários concluam as compras:

import { InsertAffiliate } from 'insert-affiliate-js-sdk';

// Initialize SDK with your company code
await InsertAffiliate.initialize('your_company_code');

Etapa 3: Passar os Dados do Afiliado para o Stripe Checkout

Ao criar uma sessão do Stripe Checkout, inclua ambos os campos obrigatórios nos três locais de metadados para garantir o rastreamento correto:

// Get the current affiliate identifier and company ID
const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
const companyId = await InsertAffiliate.returnCompanyId();

// Create Stripe checkout session with metadata
const session = await stripe.checkout.sessions.create({
  line_items: [
    {
      price: 'price_1234',
      quantity: 1,
    },
  ],
  mode: 'subscription',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  // 1. Session metadata (available in checkout.session.completed event)
  metadata: {
    insertAffiliate: affiliateId || '',
    insertAffiliateCompanyId: companyId || '',
  },
  // 2. Subscription metadata (persists with subscription)
  subscription_data: {
    metadata: {
      insertAffiliate: affiliateId || '',
      insertAffiliateCompanyId: companyId || '',
    },
  },
  // 3. Payment Intent metadata (available on each payment)
  payment_intent_data: {
    metadata: {
      insertAffiliate: affiliateId || '',
      insertAffiliateCompanyId: companyId || '',
    },
  },
});

Campos de Metadados Obrigatórios

Ambos os campos a seguir são obrigatórios para a correta atribuição de afiliados:

  • insertAffiliate - O código curto (identificador) do afiliado
  • insertAffiliateCompanyId - O ID da sua empresa no Insert Affiliate

Esses campos precisam ser passados nos três locais de metadados (sessão, assinatura e payment intent) para garantir que o Insert Affiliate possa rastrear e atribuir os pagamentos corretamente.

Como Funciona em Conjunto

  1. RevenueCat gerencia o ciclo de vida da assinatura (testes, renovações, cancelamentos)
  2. Stripe processa os pagamentos efetivos
  3. Insert Affiliate rastreia a atribuição de afiliados por meio dos metadados do Stripe
  4. Seu checkout hospedado executa o SDK do Insert Affiliate para capturar a atribuição

Como você conectou a sua conta Stripe via Stripe Connect (Etapa 2), o Insert Affiliate recebe automaticamente todos os eventos do Stripe - incluindo os de assinaturas do RevenueCat - e lê os campos de metadados para creditar os afiliados.

Como Obter os Valores Necessários

Você precisa recuperar ambos os valores do SDK do Insert Affiliate. O SDK lida automaticamente com a detecção de deep links e a atribuição de afiliados.

Obtendo o Identificador do Afiliado

O identificador do afiliado pode vir de várias fontes:

  • Deep linking: Quando um usuário clica em um link de afiliado, capture o identificador por meio da sua plataforma de deep linking
  • Código curto: Os usuários podem inserir ou aplicar manualmente um código curto de afiliado
  • Parâmetros de URL: Detectados automaticamente pelo SDK

Ver documentação do JS SDK →

Obtendo o Company ID

O ID da sua empresa no Insert Affiliate também é obrigatório.

Ver documentação do JS SDK →

Passando para o Seu Backend

Envie ambos os valores ao seu backend ao criar sessões de checkout:

const response = await fetch('/create-checkout-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    priceId: 'price_1234',
    insertAffiliate: affiliateId,
    insertAffiliateCompanyId: companyId,
    successUrl: window.location.origin + '/success',
    cancelUrl: window.location.origin + '/cancel',
  }),
});

Testando a Sua Configuração

  1. Habilite o Stripe Web Payments nas suas configurações
  2. Conecte a sua conta Stripe via Stripe Connect
  3. Inicialize o SDK do Insert Affiliate na sua página de checkout
  4. Faça uma compra de teste com ambos os campos obrigatórios (insertAffiliate e insertAffiliateCompanyId) nos metadados
  5. Verifique o seu painel de transações para confirmar que a transação aparece

Solução de Problemas

Transações Não Aparecem

Verifique estes problemas comuns:

  • Status do Stripe Connect: Verifique se a sua conta Stripe aparece como "Active" nas configurações
  • Pagamentos Web habilitados: Confirme que "Stripe Web Payments" está selecionado nas configurações
  • Campos de metadados obrigatórios: Confirme que você está passando ambos insertAffiliate e insertAffiliateCompanyId nos três locais de metadados (session, subscription_data, payment_intent_data)
  • Inicialização do SDK: Garanta que o SDK do Insert Affiliate esteja inicializado corretamente na sua página de checkout e retornando valores válidos
  • Conexão Stripe do RevenueCat: Verifique se o RevenueCat está conectado corretamente à mesma conta Stripe que você conectou via Stripe Connect
  • Checkout hospedado: Confirme que o SDK do Insert Affiliate está sendo executado na sua própria página de checkout hospedada (não em uma página hospedada por terceiros)

O SDK Não Detecta o Afiliado

  • Configuração do deep link: Verifique se a sua plataforma de deep linking está configurada corretamente
  • Parâmetros de URL: Verifique se os links de afiliado incluem o parâmetro insertAffiliate correto
  • Momento da inicialização do SDK: Garanta que o SDK seja inicializado antes de os usuários chegarem à sua página de checkout

O Que Acontece em Seguida

Uma vez configurado:

  1. Compras com metadados de afiliado criam automaticamente registros de comissão
  2. Veja todas as transações no seu painel
  3. Configure as taxas de comissão por afiliado
  4. Configure métodos de pagamento para pagar os seus afiliados
  5. O RevenueCat continua a gerenciar as assinaturas enquanto o Insert Affiliate rastreia a atribuição