PosQuantum
Apenas Admin — Guia interno

Ativar Stripe em modo LIVE

Checklist passo-a-passo para fazer o corte de Stripe Test → Stripe Live e começar a receber pagamentos reais. Tempo estimado: 1–2 horas.

Progresso: 0 / 90%
Passo 1

Configurar Business Settings

Completa os dados da empresa na Stripe para ativar o modo LIVE.

  • •Entra em dashboard.stripe.com → Settings → Business settings
  • •Preenche Business details: nome legal, morada, NIF/VAT, website
  • •Preenche Banking: IBAN para receber payouts
  • •Preenche Tax information: país, taxa IVA aplicável
  • •Preenche Public details: nome público, email de suporte, telefone
Abrir Business Settings

Sem estes dados, a Stripe NÃO aceita o pedido de activação LIVE.

Passo 2

Ativar Stripe Customer Portal

Crítico: O portal do cliente em /pt/portal redirecciona para a Stripe para gerir subscrições. Tem de estar activo.

  • •Abre Settings → Billing → Customer portal
  • •Clica Activate test link + Activate live link
  • •Permite: Update payment method, View invoices, Cancel subscriptions
  • •Em Products: permite Switch plan entre Starter, Pro, Business, Enterprise
  • •Em Cancellations: permite cancelar imediatamente OU ao final do período
  • •Em Branding: envia logo PosQuantum + cor primária #00d4ff
Abrir Customer Portal Settings

Sem isto, o botão "Gerir Subscrição" no Portal Cliente dá erro 400.

Passo 3

Configurar Tax

Activa Stripe Tax para calcular IVA automaticamente por país.

  • •Abre Settings → Tax
  • •Clica Set up Stripe Tax (tanto em Test como Live)
  • •Adiciona origem fiscal: Portugal (ou o país da tua empresa)
  • •Activa automatic tax calculation
  • •Nos Products/Prices: marca Tax behavior como Exclusive (IVA somado ao preço)
Abrir Tax Settings
Passo 4

Criar Products & Prices LIVE

Cria os 4 planos em modo LIVE (espelho dos existentes em Test).

  • •Muda o toggle para Live mode (canto superior direito)
  • •Products → + Add product → cria: Starter €49/mês, Pro €149/mês, Business €499/mês, Enterprise €1499/mês
  • •Cria também Prices anuais (20% desconto): Starter €470/ano, Pro €1430/ano, Business €4790/ano, Enterprise €14390/ano
  • •Para cada Price: Copy ID (price_xxxx) — vais precisar no passo 7
  • •Adiciona Products de overage: "API Overage" (€0.001/request), "Storage Overage" (€0.10/GB/mês)
Abrir Products

Os Price IDs em LIVE são diferentes dos IDs em TEST. Anota todos.

Passo 5

Rodar Secret Key

Copia a secret key LIVE para o ficheiro .env.

  • •Em Live mode: Developers → API keys
  • •Em Standard keys: clica Reveal live key token
  • •Copy sk_live_... (guarda com segurança — só aparece uma vez)
  • •Edita .env: STRIPE_SECRET_KEY=sk_live_... (substitui sk_test_...)
  • •Nunca commits este valor ao git
STRIPE_SECRET_KEY=sk_live_51XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Abrir API keys
Passo 6

Atualizar Publishable Key

Copia a publishable key LIVE para o .env.

  • •Em Live mode: Developers → API keys → Standard keys
  • •Copy pk_live_... (esta pode ser exposta no frontend)
  • •Edita .env: NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_51XXXXXXXXXXXXXXXX
Passo 7

Configurar Webhook de Produção

Cria um endpoint webhook em Live mode apontando para o domínio de produção.

  • •Em Live mode: Developers → Webhooks → + Add endpoint
  • •URL: https://posquantum.com/api/stripe/webhook
  • •Selecciona estes 6 eventos (críticos):
  • • • checkout.session.completed
  • • • customer.subscription.created
  • • • customer.subscription.updated
  • • • customer.subscription.deleted
  • • • invoice.paid
  • • • invoice.created
  • •Clica Add endpoint → copia o Signing secret (whsec_...)
  • •Edita .env: STRIPE_WEBHOOK_SECRET=whsec_... (substitui o de Test)
STRIPE_WEBHOOK_SECRET=whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Abrir Webhooks

Se os eventos não chegam, verifica no Stripe → Webhooks → Deliveries (200 = OK).

Passo 8

Atualizar Price IDs LIVE no código

Substitui os Price IDs Test pelos Live no .env.

  • •Recolhe todos os Price IDs anotados no passo 4
  • •Edita .env com os IDs LIVE (exemplo em baixo):
STRIPE_PRICE_STARTER_MONTHLY=price_1XXXXXX_live
STRIPE_PRICE_STARTER_YEARLY=price_1XXXXXX_live
STRIPE_PRICE_PRO_MONTHLY=price_1XXXXXX_live
STRIPE_PRICE_PRO_YEARLY=price_1XXXXXX_live
STRIPE_PRICE_BUSINESS_MONTHLY=price_1XXXXXX_live
STRIPE_PRICE_BUSINESS_YEARLY=price_1XXXXXX_live
STRIPE_PRICE_ENTERPRISE_MONTHLY=price_1XXXXXX_live
STRIPE_PRICE_ENTERPRISE_YEARLY=price_1XXXXXX_live
STRIPE_PRICE_OVERAGE_API=price_1XXXXXX_live
STRIPE_PRICE_OVERAGE_STORAGE=price_1XXXXXX_live
Passo 9

Testar Fluxo Completo

Faz um test charge real (€1.00) + refund para validar end-to-end.

  • •Reinicia o servidor de produção (deploy novo após .env atualizado)
  • •Abre posquantum.com/pt/pricing → escolhe Starter mensal
  • •Cria subscription com cartão real (vai cobrar €49)
  • •Verifica: email de confirmação chegou? Webhook invoice.paid processado? Subscription aparece no Portal Cliente?
  • •Abre dashboard.stripe.com → Payments → encontra o pagamento → Refund (prevenção de charge falso)
  • •Cancela a subscription: no Portal Cliente clica "Cancel at period end"
  • •Valida: Admin dashboard actualiza KPIs? churnRate reflect cancelamento?

Checklist final antes de anunciar

  • Todos os 9 passos completos (tick verde)
  • Test charge €1 + refund funcionou
  • Stripe → Webhooks → Deliveries: todos 200 OK
  • Admin dashboard reflecte pagamento real
  • Email de confirmação chega ao cliente
  • Portal Cliente /pt/portal abre Stripe Billing Portal
  • Cancellation por customer funciona
  • Invoice PDF descarrega correctamente
← Voltar ao Admin Dashboard