Pular para o conteúdo principal

Gateways de Pagamento (Stripe e PayPal)

O FeedbackPulse SaaS suporta Stripe e PayPal para faturamento por assinatura. Você pode habilitar um ou ambos.

💰 Como Funciona o Faturamento​

  1. Você cria planos de assinatura em Admin → Planos (ex.: Starter $9,99/mês, Pro $29,99/mês)
  2. Cada plano tem um Stripe Price ID e/ou PayPal Plan ID
  3. Quando um tenant assina, é redirecionado para o Stripe Checkout ou PayPal
  4. Após o pagamento, o FeedbackPulse ativa a assinatura
  5. Os webhooks mantêm tudo sincronizado (renovações, cancelamentos, falhas)

💳 Configuração do Stripe​

Etapa 1: Criar uma Conta no Stripe​

  1. Cadastre-se em stripe.com
  2. Conclua a verificação de identidade
  3. Obtenha suas chaves de API em Developers → API Keys

Etapa 2: Obter Suas Chaves de API​

ChaveOnde EncontrarVariável .env
Chave PublicávelDashboard → Developers → API KeysSTRIPE_PUBLISHABLE_KEY
Chave SecretaDashboard → Developers → API KeysSTRIPE_SECRET_KEY
STRIPE_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxxxxxx
STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxx

🧪 Testes: Use as chaves pk_test_ e sk_test_ para o modo sandbox.

Etapa 3: Criar Produtos e Preços no Stripe​

Para cada plano de assinatura, crie um preço recorrente no Stripe:

  1. Vá para Products → Add Product
  2. Nome: "FeedbackPulse Starter" (ou o nome do seu plano)
  3. Adicione um preço recorrente: $9,99 / mês
  4. Opcionalmente, adicione um preço anual: $99,99 / ano
  5. Copie o Price ID (começa com price_)

Etapa 4: Vincular Preços aos Planos​

No FeedbackPulse, vá para Admin → Planos → Editar:

Campo do PlanoValor do Stripe
ID de Preço Mensal do Stripeprice_xxxxxxxxx (ID do preço mensal)
ID de Preço Anual do Stripeprice_xxxxxxxxx (ID do preço anual)

Etapa 5: Configurar Webhooks do Stripe​

Isso é crítico — os webhooks mantêm as assinaturas sincronizadas.

  1. Vá para Stripe Dashboard → Developers → Webhooks
  2. Clique em Add endpoint
  3. URL do Endpoint: https://yourdomain.com/webhooks/stripe
  4. Eventos para escutar:
    • checkout.session.completed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • invoice.payment_failed
  5. Copie o Signing Secret (começa com whsec_)
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxx

Etapa 6: Habilitar no Painel de Admin​

Vá para Admin → Configurações → Pagamentos:

  • Ative o Stripe
  • Cole suas chaves publicável e secreta
  • Salve

💰 Configuração do PayPal​

Etapa 1: Criar uma Conta Business no PayPal​

  1. Cadastre-se em paypal.com/business
  2. Vá para developer.paypal.com

Etapa 2: Criar um App de API REST​

  1. Vá para Dashboard → Apps & Credentials
  2. Clique em Create App
  3. Nome: "FeedbackPulse"
  4. Copie o Client ID e o Secret
PAYPAL_CLIENT_ID=your_client_id
PAYPAL_CLIENT_SECRET=your_client_secret
PAYPAL_MODE=live

🧪 Testes: Use PAYPAL_MODE=sandbox e credenciais de sandbox.

Etapa 3: Criar Planos de Assinatura no PayPal​

  1. Vá para PayPal Developer Dashboard → Subscriptions → Plans
  2. Crie um produto primeiro, depois crie planos para ele
  3. Copie cada Plan ID (começa com P-)

Etapa 4: Vincular Planos no FeedbackPulse​

Em Admin → Planos → Editar:

Campo do PlanoValor do PayPal
ID do Plano Mensal do PayPalP-xxxxxxxxx (plano mensal)
ID do Plano Anual do PayPalP-xxxxxxxxx (plano anual)

Etapa 5: Configurar Webhooks do PayPal​

  1. No PayPal Developer Dashboard → Webhooks
  2. Adicione a URL do webhook: https://yourdomain.com/webhooks/paypal
  3. Selecione os eventos:
    • BILLING.SUBSCRIPTION.CREATED
    • BILLING.SUBSCRIPTION.ACTIVATED
    • BILLING.SUBSCRIPTION.UPDATED
    • BILLING.SUBSCRIPTION.CANCELLED
    • BILLING.SUBSCRIPTION.SUSPENDED
    • PAYMENT.SALE.COMPLETED
  4. Copie o Webhook ID
PAYPAL_WEBHOOK_ID=your_webhook_id

Etapa 6: Habilitar no Painel de Admin​

Vá para Admin → Configurações → Pagamentos:

  • Ative o PayPal
  • Cole seu Client ID e Secret
  • Salve

🧪 Testando Pagamentos​

Modo de Teste do Stripe​

Use números de cartão de teste:

  • Sucesso: 4242 4242 4242 4242
  • Recusado: 4000 0000 0000 0002
  • 3D Secure: 4000 0025 0000 3155

Validade: qualquer data futura. CVV: qualquer 3 dígitos.

Sandbox do PayPal​

  1. Vá para developer.paypal.com → Sandbox → Accounts
  2. Use a conta de comprador sandbox gerada para testar pagamentos

Suporte a Múltiplas Moedas​

Os planos podem receber moedas diferentes (ex.: USD, EUR, BRL). Configure a lista de moedas suportadas em Admin > Configurações > Pagamentos no campo Moedas Suportadas.

  • Stripe: As sessões de checkout passam automaticamente a moeda do plano, de modo que os clientes são cobrados na moeda correta.
  • PayPal: As solicitações de assinatura incluem metadados de moeda correspondentes à moeda configurada no plano.
  • A moeda é armazenada em cada fatura para manter registros precisos.

Para detalhes sobre a configuração de moedas suportadas, consulte Configurações da Plataforma.

🔒 Notas de Segurança​

  • As chaves de API são armazenadas criptografadas na tabela platform_settings
  • As assinaturas dos webhooks são verificadas (HMAC do Stripe, validação de assinatura do PayPal)
  • Os eventos de pagamento são registrados na tabela payment_events (Admin → Pagamentos)
  • A deduplicação de eventos previne o processamento duplo de webhooks

⏭️ Próximos Passos​