Transações Web do Stripe

Acompanhe comissões sobre compras feitas por meio do Stripe Checkout e assinaturas no seu site - não apenas compras dentro do app.

Quando você ativa Stripe Web Payments nas suas configurações, você pode acompanhar transações web junto com suas compras mobile.

O Que Você Pode Acompanhar

Após a configuração, o Insert Affiliate acompanha automaticamente:

  • Compras pelo Stripe Checkout (avulsas e por assinatura)
  • Compras iniciais de assinatura
  • Renovações de assinatura

Guia de Configuração

Passo 1: Ative o Web Payments

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

Passo 2: Configure o Stripe Connect

Antes de poder acompanhar transações web, você precisa conectar sua conta do 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 existente do Stripe, OU
    • Crie uma nova conta do Stripe
    • 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 quando concluir

Indicadores de status:

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

Pronto! O acompanhamento de transações web agora está ativo.

Implementação: Passando os Códigos de Afiliado

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

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: insertAffiliate || '',
    insertAffiliateCompanyId: insertAffiliateCompanyId || '',
  },
  // 2. Subscription metadata (persists with subscription)
  subscription_data: {
    metadata: {
      insertAffiliate: insertAffiliate || '',
      insertAffiliateCompanyId: insertAffiliateCompanyId || '',
    },
  },
  // 3. Payment Intent metadata (available on each payment)
  payment_intent_data: {
    metadata: {
      insertAffiliate: insertAffiliate || '',
      insertAffiliateCompanyId: insertAffiliateCompanyId || '',
    },
  },
});

Campos de Metadados Obrigatórios

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

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

Esses campos devem ser passados em todos os três locais de metadados (session, subscription e payment intent) para garantir que o Insert Affiliate consiga acompanhar e atribuir os pagamentos corretamente.

Como Obter os Valores Necessários

Você precisa recuperar ambos os valores no SDK do Insert Affiliate. Consulte a documentação do SDK da sua plataforma para detalhes específicos de implementação.

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 pela sua plataforma de deep linking
  • Código curto: Os usuários podem inserir ou aplicar manualmente um código curto de afiliado

Veja a documentação do JS SDK →

Obtendo o Company ID

O ID da sua empresa no Insert Affiliate também é necessário.

Veja a documentação do JS SDK →

Passando para o Seu Backend

Envie ambos os valores ao seu backend ao criar as 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',
  }),
});

Acompanhando Itens de Linha Específicos

Por padrão, o Insert Affiliate acompanha o valor total da fatura. Se sua fatura contém vários itens de linha, mas você quer pagar comissão apenas sobre um subconjunto deles, você pode especificar quais price IDs do Stripe devem gerar comissão.

Adicione o campo opcional insertAffiliateTrackedPrices aos metadados de subscription_data como uma lista de price IDs do Stripe separados por vírgula:

subscription_data: {
  metadata: {
    insertAffiliate: insertAffiliate || '',
    insertAffiliateCompanyId: insertAffiliateCompanyId || '',
    insertAffiliateTrackedPrices: 'price_abc123,price_def456', // optional
  },
},

Como Funciona

  • Apenas os itens de linha que correspondem aos price IDs listados contribuem para o cálculo da comissão
  • Os itens de linha que não estão na lista são excluídos do valor bruto
  • Se você tiver uma taxa fixa de plataforma configurada (por exemplo, os $0.30 do Stripe), ela é rateada proporcionalmente entre os itens de linha acompanhados e não acompanhados, de modo que apenas a parcela acompanhada é deduzida — a taxa fixa total não é cobrada sobre um valor acompanhado pequeno

Quando Usar Isto

Isso é útil quando uma única fatura cobre vários produtos ou serviços, mas o afiliado deve receber comissão apenas sobre alguns deles — por exemplo, se um item de linha é uma taxa de configuração e outro é uma assinatura recorrente.

Se insertAffiliateTrackedPrices for omitido, a fatura completa é acompanhada normalmente.

Testando Sua Configuração

Nota Importante Sobre Testes

O Insert Affiliate atualmente roda apenas em uma instância de produção do Stripe Connect. Isso significa que:

  • Você não pode usar o modo de teste do Stripe nem números de cartão de teste
  • Você deve usar métodos de pagamento reais para testar
  • Solução alternativa recomendada: Crie um código promocional no seu Stripe Dashboard para tornar as transações de teste gratuitas ou de custo muito baixo (por exemplo, $0.01)

Passos de Teste

  1. Ative o Stripe Web Payments nas suas configurações
  2. Conecte sua conta do Stripe via Stripe Connect
  3. (Opcional, mas recomendado) Crie um código promocional no seu Stripe Dashboard para 100% de desconto ou um valor mínimo
  4. Faça uma compra real com ambos os campos obrigatórios (insertAffiliate e insertAffiliateCompanyId) nos metadados
  5. Aplique seu código promocional se você criou um
  6. Verifique 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: Confirme que sua conta do Stripe aparece como "Active" nas configurações
  • Web Payments ativado: Confirme que "Stripe Web Payments" está selecionado nas configurações
  • Campos de metadados obrigatórios: Confirme que você está passando ambos insertAffiliate e insertAffiliateCompanyId em todos os três locais de metadados (session, subscription_data, payment_intent_data)
  • Inicialização do SDK: Garanta que o SDK do Insert Affiliate está inicializado corretamente e retornando valores válidos para ambos os campos

O Que Acontece a Seguir

Após a configuração:

  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 os métodos de pagamento para pagar seus afiliados

Precisa de Ajuda?

Se você encontrar algum problema durante a configuração, entre em contato com o suporte e nós ajudaremos você a configurar.