Gerenciamento de Assinaturas

Tudo o que você precisa para gerenciar cobranças recorrentes através da stryhub. Da criação de assinaturas ao tratamento de upgrades, cancelamentos, testes gratuitos e pagamentos falhos — tudo integrado com o Stripe.

Visão Geral

A stryhub oferece gerenciamento completo de assinaturas sobre a sua conta Stripe existente. Você não precisa construir infraestrutura de cobrança do zero — conecte sua conta Stripe, e a stryhub cuida do resto.

Principais funcionalidades:

• Cobrança automática — O Stripe gerencia as cobranças recorrentes por você
• Portal do cliente — Permita que os clientes gerenciem suas próprias assinaturas (atualizar forma de pagamento, trocar de plano, cancelar)
• Upgrades e downgrades — Rateio automático quando clientes mudam de plano
• Pausar e retomar — Suspenda temporariamente a cobrança sem cancelar
• Período de teste gratuito — Ofereça períodos de teste antes da primeira cobrança
• Cobrança automática inteligente — O Stripe retenta automaticamente pagamentos falhos usando aprendizado de máquina
• Webhooks em tempo real — Seja notificado de cada evento de assinatura no seu SaaS
• Analytics — Acompanhe MRR, taxa de churn, assinaturas ativas e receita pelo painel

Como Funciona

A stryhub fica entre o Stripe e o seu SaaS, atuando como uma camada de gerenciamento:

1. Stripe armazena seus produtos, preços e processa os pagamentos
2. stryhub lê seus produtos automaticamente, gera páginas de checkout, gerencia assinaturas e acompanha analytics
3. Seu SaaS recebe eventos de webhook da stryhub para conceder/revogar acesso, enviar e-mails e atualizar seu banco de dados

Ciclo de Vida da Assinatura

Cada assinatura passa por uma série de estados. Entender esses estados é essencial para gerenciar o acesso no seu SaaS.

Transições de estado

trialing ──> active ──> canceled
                │
                ├──> past_due ──> active (pagamento realizado)
                │        │
                │        └──> unpaid ──> canceled
                │
                └──> paused ──> active (retomada)
                         │
                         └──> canceled

incomplete ──> active (pagamento realizado)
     │
     └──> incomplete_expired (timeout de 23h)

Configurando Produtos

A stryhub possui um sistema completo de gerenciamento de produtos e preços integrado ao painel. Você pode criar produtos, definir preços, personalizar opções de checkout e obter links de pagamento compartilháveis — tudo em um passo, sem precisar abrir o Stripe Dashboard.

Criando um produto na stryhub

1. No painel administrativo, acesse Programs e clique no ícone de Products ao lado do seu programa
2. Clique em New Product
3. Preencha os detalhes do produto:
   • Name — o nome do produto que seus clientes verão
   • Description — descrição opcional
   • Image — imagem do produto (JPEG, PNG ou WEBP, máximo 2MB)
   • Statement descriptor — o que aparece na fatura do cartão de crédito do cliente (máximo 22 caracteres)
   • Unit label — ex.: "licença", "vaga", "usuário"
4. Defina o preço:
   • Amount — o valor do preço (ex.: 29,90)
   • Currency — BRL, USD ou EUR
   • Type — Recurring (assinatura) ou One-time (compra avulsa)
   • Billing interval (para recorrente): Diário, Semanal, Mensal, Trimestral, Anual ou personalizado
5. Configure as opções de checkout (veja abaixo)
6. Clique em Create

Personalização do checkout

Ao criar um produto (ou editar um link de pagamento posteriormente), você pode configurar quais dados são coletados no checkout:

Adicionando mais preços a um produto

Você pode adicionar múltiplos preços ao mesmo produto — por exemplo, um plano mensal e um anual:

1. Acesse Products no seu programa
2. Clique no botão + ao lado do produto
3. Defina o novo valor, moeda e intervalo
4. Cada preço recebe seu próprio link de checkout e Payment Link

Exemplos de configuração de preços

Gerenciando produtos e preços

Na página de Products no painel, você pode:

• Arquivar/desarquivar produtos e preços — itens arquivados ficam ocultos no checkout mas são preservados no Stripe
• Ocultar preços de afiliados — controle quais preços os afiliados podem promover
• Definir comissão personalizada por preço — substitua a taxa de comissão padrão do programa para preços específicos
• Editar opções do link de pagamento — atualize a personalização do checkout (coleta de dados, campos personalizados, mensagem de conclusão) a qualquer momento

Já tem produtos no Stripe?

Se você está conectando uma conta Stripe existente que já possui produtos e preços, eles são sincronizados automaticamente. Você não precisa recriar nada.

• Produtos e preços são importados quando você conecta sua conta Stripe
• Use o botão "Sync Data" no painel administrativo para importar assinaturas e clientes existentes
• Você pode criar novos produtos na stryhub ao lado dos seus produtos Stripe existentes

Checkout e Criação de Assinatura

Quando você cria um produto na stryhub, dois tipos de links de checkout são gerados automaticamente:

1. Payment Link (vendas diretas)

Um Payment Link compartilhável do Stripe é criado automaticamente para cada preço. Você pode encontrá-lo na página de Products — basta copiar o link e compartilhar em qualquer lugar (site, e-mail, redes sociais). Sem necessidade de rastreamento de afiliados.

2. Link de checkout de afiliado

Para vendas rastreadas por afiliados, o formato é:

https://app.stryhub.com/checkout/{affiliate_ref_code}/{stripe_price_id}

Os afiliados veem seus links personalizados de checkout na página "My Links". Cada link tem o código de referência incorporado, então as comissões são rastreadas automaticamente.

O que acontece após o checkout

1. O cliente conclui o pagamento na página de checkout hospedada pelo Stripe
2. O Stripe cria a assinatura e cobra a primeira fatura
3. A stryhub recebe o evento e cria o registro da assinatura
4. A stryhub dispara os seguintes webhooks para o seu SaaS:
   • checkout.completed — sessão de checkout concluída
   • payment.completed — primeiro pagamento realizado com sucesso
   • subscription.created — nova assinatura ativa
5. Se a venda veio por um link de afiliado, a comissão é calculada e transferida automaticamente

Métodos de pagamento suportados

Você escolhe quais métodos de pagamento aceitar ao criar o produto:

• Cartão de crédito/débito — Visa, Mastercard, Amex e outros
• Boleto Bancário — boleto bancário brasileiro (disponível para assinaturas e compras avulsas)
• PIX — pagamento instantâneo brasileiro (apenas compras avulsas)

Tratando Webhooks

Esta é a seção mais importante se você deseja automatizar o controle de acesso no seu SaaS. A stryhub encaminha eventos de assinatura para seus endpoints de webhook como payloads simplificados e consistentes.

Referência de eventos de assinatura

Exemplo: handler completo de webhook

Aqui está um exemplo completo de como tratar eventos de assinatura no seu SaaS. Este código verifica a assinatura do webhook e roteia cada evento para o handler apropriado.

const crypto = require('crypto');
const express = require('express');
const app = express();

const WEBHOOK_SECRET = process.env.STRYHUB_WEBHOOK_SECRET;

// IMPORTANTE: use express.raw() para obter o corpo bruto para verificação de assinatura
app.post('/webhooks/stryhub', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-stryhub-signature'];

  // 1. Verificar assinatura
  if (!verifySignature(req.body.toString(), signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  const { type, data } = event;

  // 2. Tratar cada tipo de evento
  switch (type) {
    case 'checkout.completed':
      // Novo cliente acabou de comprar — criar conta
      await createUserAccount({
        email: data.customer.email,
        name: data.customer.name,
        stripeCustomerId: data.customer.stripe_customer_id,
        subscriptionId: data.subscription_id,
        plan: data.mode, // 'subscription' ou 'payment'
      });
      break;

    case 'subscription.created':
      // Assinatura agora ativa — conceder acesso
      await grantAccess(data.customer.stripe_customer_id, data.subscription_id);
      break;

    case 'subscription.renewed':
      // Pagamento recorrente bem-sucedido — estender acesso
      await extendAccess(data.customer.stripe_customer_id, data.subscription_id);
      break;

    case 'subscription.canceled':
      // Assinatura cancelada — revogar acesso
      await revokeAccess(data.customer.stripe_customer_id, data.subscription_id);
      await sendEmail(data.customer.email, 'Your subscription has been canceled');
      break;

    case 'subscription.paused':
      // Assinatura pausada — limitar acesso
      await pauseAccess(data.customer.stripe_customer_id, data.subscription_id);
      break;

    case 'subscription.resumed':
      // Assinatura retomada — restaurar acesso
      await grantAccess(data.customer.stripe_customer_id, data.subscription_id);
      break;

    case 'payment.failed':
      // Pagamento falhou — notificar cliente
      await sendEmail(data.customer.email, 'Your payment failed. Please update your payment method.');
      break;

    case 'subscription.past_due':
      // Fatura em atraso — mostrar aviso (manter acesso durante período de carência)
      await flagPastDue(data.customer.stripe_customer_id, data.subscription_id);
      break;

    case 'customer.created':
      // Novo cliente — armazenar no banco de dados
      await createCustomerRecord(data.customer);
      break;
  }

  // 3. Sempre responder 200 rapidamente
  res.status(200).json({ received: true });
});

function verifySignature(rawBody, signatureHeader, secret) {
  const parts = {};
  signatureHeader.split(',').forEach(p => {
    const [key, value] = p.split('=');
    parts[key] = value;
  });
  const signedContent = `${parts['t']}.${rawBody}`;
  const expected = crypto.createHmac('sha256', secret).update(signedContent).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(parts['v1'], 'hex'), Buffer.from(expected, 'hex'));
}

import hmac, hashlib, json, os
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['STRYHUB_WEBHOOK_SECRET']

@app.route('/webhooks/stryhub', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Stryhub-Signature', '')

    # 1. Verificar assinatura
    if not verify_signature(request.data, signature, WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = json.loads(request.data)
    event_type = event['type']
    data = event['data']

    # 2. Tratar cada tipo de evento
    if event_type == 'checkout.completed':
        create_user_account(
            email=data['customer']['email'],
            name=data['customer']['name'],
            stripe_customer_id=data['customer']['stripe_customer_id'],
            subscription_id=data.get('subscription_id'),
        )

    elif event_type == 'subscription.created':
        grant_access(data['customer']['stripe_customer_id'], data['subscription_id'])

    elif event_type == 'subscription.renewed':
        extend_access(data['customer']['stripe_customer_id'], data['subscription_id'])

    elif event_type == 'subscription.canceled':
        revoke_access(data['customer']['stripe_customer_id'], data['subscription_id'])
        send_email(data['customer']['email'], 'Your subscription has been canceled')

    elif event_type == 'subscription.paused':
        pause_access(data['customer']['stripe_customer_id'], data['subscription_id'])

    elif event_type == 'subscription.resumed':
        grant_access(data['customer']['stripe_customer_id'], data['subscription_id'])

    elif event_type == 'payment.failed':
        send_email(data['customer']['email'], 'Your payment failed. Please update your payment method.')

    elif event_type == 'subscription.past_due':
        flag_past_due(data['customer']['stripe_customer_id'], data['subscription_id'])

    elif event_type == 'customer.created':
        create_customer_record(data['customer'])

    # 3. Sempre responder 200 rapidamente
    return jsonify({'received': True}), 200

def verify_signature(raw_body, signature_header, secret):
    parts = dict(p.split('=', 1) for p in signature_header.split(','))
    signed_content = f"{parts['t']}.{raw_body.decode('utf-8')}"
    expected = hmac.new(secret.encode(), signed_content.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

<?php
$webhookSecret = getenv('STRYHUB_WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_STRYHUB_SIGNATURE'] ?? '';

// 1. Verificar assinatura
if (!verifySignature($rawBody, $signature, $webhookSecret)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

$event = json_decode($rawBody, true);
$type = $event['type'];
$data = $event['data'];

// 2. Tratar cada tipo de evento
switch ($type) {
    case 'checkout.completed':
        createUserAccount(
            $data['customer']['email'],
            $data['customer']['name'],
            $data['customer']['stripe_customer_id'],
            $data['subscription_id'] ?? null
        );
        break;

    case 'subscription.created':
        grantAccess($data['customer']['stripe_customer_id'], $data['subscription_id']);
        break;

    case 'subscription.renewed':
        extendAccess($data['customer']['stripe_customer_id'], $data['subscription_id']);
        break;

    case 'subscription.canceled':
        revokeAccess($data['customer']['stripe_customer_id'], $data['subscription_id']);
        sendEmail($data['customer']['email'], 'Your subscription has been canceled');
        break;

    case 'subscription.paused':
        pauseAccess($data['customer']['stripe_customer_id'], $data['subscription_id']);
        break;

    case 'subscription.resumed':
        grantAccess($data['customer']['stripe_customer_id'], $data['subscription_id']);
        break;

    case 'payment.failed':
        sendEmail($data['customer']['email'], 'Payment failed. Please update your payment method.');
        break;

    case 'subscription.past_due':
        flagPastDue($data['customer']['stripe_customer_id'], $data['subscription_id']);
        break;

    case 'customer.created':
        createCustomerRecord($data['customer']);
        break;
}

// 3. Sempre responder 200 rapidamente
http_response_code(200);
echo json_encode(['received' => true]);

function verifySignature(string $rawBody, string $signatureHeader, string $secret): bool {
    $parts = [];
    foreach (explode(',', $signatureHeader) as $part) {
        [$key, $value] = explode('=', $part, 2);
        $parts[$key] = $value;
    }
    $signedContent = "{$parts['t']}.{$rawBody}";
    $expected = hash_hmac('sha256', $signedContent, $secret);
    return hash_equals($parts['v1'] ?? '', $expected);
}
?>

Portal do Cliente

O Stripe Billing Portal é uma página segura, hospedada pelo Stripe, onde seus clientes podem gerenciar suas próprias assinaturas — sem que você precise construir nenhuma interface.

O que os clientes podem fazer

• Atualizar a forma de pagamento (cartão de crédito, etc.)
• Trocar de plano (upgrade ou downgrade)
• Cancelar a assinatura
• Visualizar histórico de faturas e baixar recibos

Configuração

No painel administrativo da stryhub, acesse Billing Portal para configurar quais funcionalidades estão disponíveis:

Abrindo o portal para um cliente

No painel administrativo da stryhub, acesse Customers, clique em um cliente e use o botão "Open Customer Portal". Isso gera um link seguro e de uso único que redireciona o cliente para sua página de gerenciamento hospedada pelo Stripe.

Recursos avançados do portal

• O portal suporta 40+ idiomas (detectados automaticamente pelo navegador do cliente)
• 14+ métodos de pagamento suportados (cartões de crédito/débito, Apple Pay, Google Pay, SEPA e métodos locais)
• Prevenção de churn integrada: quando um cliente tenta cancelar, a Stripe pode apresentar automaticamente uma oferta de desconto para retê-lo
• Coleta de motivos de cancelamento: quando clientes cancelam, seus motivos são coletados para insights de melhoria do produto
• O portal é totalmente hospedado pela Stripe — zero desenvolvimento de frontend necessário

Upgrades e Downgrades

Quando um cliente muda de plano (ex.: de Básico para Pro), o Stripe automaticamente faz o rateio — calculando o crédito pelo tempo não utilizado no plano antigo e cobrando a diferença do plano novo.

Como o rateio funciona

Exemplo: Cliente no plano de R$50/mês faz upgrade para R$100/mês no dia 15 de um ciclo de 30 dias:

• Crédito pelo tempo não utilizado no plano antigo: R$25,00 (15 dias restantes a R$50/mês)
• Cobrança pelo tempo restante no plano novo: R$50,00 (15 dias restantes a R$100/mês)
• Cobrança líquida: R$25,00 (faturado imediatamente ou adicionado à próxima fatura)

Como os clientes fazem upgrade/downgrade

1. Através do Portal do Cliente (se troca de plano estiver habilitada)
2. Através do Stripe Dashboard diretamente
3. Via Stripe API a partir do backend do seu SaaS

Quando uma mudança de plano acontece, a stryhub dispara um webhook subscription.created com os detalhes atualizados da assinatura (novo preço, novo valor).

Cancelamentos

Assinaturas podem ser canceladas de duas formas:

Quem pode cancelar

• Administrador — pelo painel da stryhub (página de Subscriptions), com opção de escolher cancelamento imediato ou ao final do período
• Cliente — pelo Portal do Cliente (se o cancelamento estiver habilitado)

Webhook disparado

Quando uma assinatura é cancelada, a stryhub dispara subscription.canceled com os detalhes do cliente e o timestamp do cancelamento. Seu SaaS deve revogar o acesso ao receber este evento.

Pausar e Retomar

Em vez de cancelar, você pode pausar uma assinatura. Isso interrompe a cobrança mantendo o registro da assinatura intacto — facilitando o retorno do cliente.

Como funciona

• Pausar: A cobrança é interrompida. Faturas geradas durante a pausa são anuladas. O status da assinatura muda para paused.
• Retomar: A cobrança é reiniciada. A próxima fatura é gerada no início do novo ciclo de cobrança. A assinatura retorna para active.

Ações do administrador

No painel da stryhub, acesse Subscriptions, encontre uma assinatura ativa e clique em Pause. Para retomar, encontre a assinatura pausada e clique em Resume.

Webhooks disparados

• subscription.paused — quando a assinatura é pausada
• subscription.resumed — quando a assinatura é retomada

Período de Teste Gratuito

O período de teste gratuito permite que os clientes experimentem seu produto antes de serem cobrados. Durante o teste, a assinatura existe com status trialing.

Configurando testes gratuitos

Os testes gratuitos são configurados no nível do preço no Stripe. Você pode configurar isso ao criar um preço no Stripe Dashboard:

1. Edite o preço do seu produto e procure a opção Free trial
2. Defina o número de dias de teste (ex.: 7 ou 14)
3. Escolha o que acontece quando o teste termina sem forma de pagamento:
   • Cancel — a assinatura é cancelada automaticamente
   • Pause — a assinatura é pausada até o cliente adicionar uma forma de pagamento

Linha do tempo do teste

Pagamentos Falhos e Cobrança Automática

Quando um pagamento recorrente falha, o Stripe não desiste imediatamente. Ele usa Smart Retries — um sistema de aprendizado de máquina que analisa padrões de pagamento para determinar o momento ideal para retentar.

O que acontece quando um pagamento falha

1. O Stripe tenta cobrar a forma de pagamento do cliente
2. Se falhar, o Stripe agenda tentativas automáticas nas próximas semanas
3. O status da assinatura muda para past_due
4. A stryhub dispara os webhooks payment.failed e subscription.past_due
5. O Stripe envia e-mails de cobrança automaticamente para o cliente
6. Se uma tentativa for bem-sucedida, a assinatura retorna para active
7. Se todas as tentativas falharem, a assinatura pode ser cancelada (configurável no Stripe Dashboard)

O que seu SaaS deve fazer

Configurando o comportamento de tentativas

No seu Stripe Dashboard > Settings > Billing > Automatic collection, você pode configurar:

• Programação de tentativas — Smart Retries (recomendado) ou programação personalizada
• Ação para pagamento falho — Cancelar assinatura, marcar como unpaid ou deixar como past_due
• E-mails para clientes — Habilitar/desabilitar e-mails automáticos de cobrança do Stripe

Como as Smart Retries funcionam

• As retentativas inteligentes são alimentadas pelo motor de machine learning da Stripe, não por agendas fixas
• O ML analisa fuso horário, padrões de dispositivo, sinais da rede de cartões e dados cross-network para determinar o momento ideal de retentativa
• Até 8 tentativas automáticas de retentativa ao longo de aproximadamente 2 semanas
• Atualização Automática de Cartão: Quando o banco de um cliente emite um novo cartão (vencimento, substituição), a Stripe recebe automaticamente os dados atualizados das redes Visa/Mastercard — a assinatura continua sem interrupção e sem o cliente precisar fazer nada. Isso elimina o churn involuntário por cartões vencidos.

Pagamentos Globais e Conformidade

stryhub + Stripe suporta pagamentos de clientes do mundo inteiro com conformidade enterprise integrada.

Suporte Multi-Moeda

Aceite pagamentos em 135+ moedas com conversão automática de câmbio. Clientes pagam na moeda local enquanto você recebe na sua. A Stripe cuida de todos os cálculos de taxa de câmbio.

3D Secure e Conformidade SCA

Para clientes europeus, a Autenticação Forte do Cliente (SCA) é exigida pela PSD2. A Stripe aciona automaticamente a autenticação 3D Secure quando necessário, garantindo que suas assinaturas estejam em conformidade com as regulamentações europeias sem desenvolvimento adicional.

Automação de Impostos (Stripe Tax)

O Stripe Tax calcula e coleta automaticamente o valor correto de impostos com base na localização do cliente:

• IVA — União Europeia
• GST — Austrália, Nova Zelândia, Singapura e outros
• Sales Tax — Estados Unidos (estadual e local)

A Stripe monitora suas obrigações fiscais e alerta quando você se aproxima dos limites de registro em novas jurisdições. Faturas com conformidade fiscal são geradas automaticamente.

Migração para a stryhub

Se você já usa o Stripe (ou outra plataforma), migrar para a stryhub é simples. Seus dados existentes permanecem intactos.

Migração passo a passo

1. Crie sua conta na stryhub em app.stryhub.com
2. Conecte sua conta Stripe existente — acesse Configurações e clique em "Connect Stripe Account." Seus produtos, preços e clientes são sincronizados automaticamente.
3. Sincronize dados existentes — use o botão "Sync Data" no painel administrativo para importar todas as assinaturas e clientes existentes do Stripe.
4. Configure os endpoints de webhook — acesse Webhooks e adicione o endpoint do seu SaaS para começar a receber eventos.
5. Atualize seu SaaS — implemente um handler de webhook (veja Tratando Webhooks acima) para gerenciar acesso com base nos eventos de assinatura.
6. Configure o Portal do Cliente — acesse Billing Portal e habilite as funcionalidades que deseja (cancelamento, troca de plano, atualização de pagamento).
7. Substitua os links de checkout — troque suas URLs de checkout antigas pelos links de checkout da stryhub. Assinaturas existentes continuam funcionando — apenas novas compras usam o checkout da stryhub.
8. Configure afiliados (opcional) — crie um programa de afiliados para aumentar suas vendas. Veja o guia de Programas de Afiliados.

Vindo de outra plataforma?

Se você está migrando de uma plataforma que não usa Stripe (ex.: Paddle, Gumroad, PayPal), será necessário:

1. Criar uma conta Stripe, caso ainda não tenha
2. Recriar seus produtos e preços no Stripe
3. Pedir aos clientes existentes para reassinarem pelo novo link de checkout da stryhub
4. Executar ambos os sistemas em paralelo até que todos os clientes tenham migrado