STRIPE_TESTING_GUIDE.md

🧪 Guía de Testing Local con Stripe CLI

Descripción

Usa Stripe CLI para probar webhooks localmente sin necesidad de deploy a producción.

---

1️⃣ Instalar Stripe CLI

Windows (con Chocolatey):

choco install stripe-cli

Windows (Manual):

1. Descarga de: https://github.com/stripe/stripe-cli/releases
2. Descomprime en C:\Program Files\stripe-cli
3. Agrega a PATH (o usa ruta completa)

Verificar instalación:

stripe --version
# Salida esperada: v1.x.x

---

2️⃣ Login con Stripe

stripe login

Te abrirá un navegador para autorizar. Haz click "Allow" y vuelve a la terminal.

Done ✅ cuando veas:

✓ Authenticated with Stripe

---

3️⃣ Configurar Webhook Local

En una terminal, ejecuta:

stripe listen --forward-to localhost:3000/api/payments/webhook

Salida:

Getting ready to listen for live events...
Ready! You are now listening for Stripe events.

Webhook signing secret for whsec_XXXXX

IMPORTANTE: Copia ese whsec_XXXXX y actualiza tu .env:

STRIPE_WEBHOOK_SECRET="whsec_XXXXX"

---

4️⃣ Iniciar Servidor (otra terminal)

npm run dev
# Server running at localhost:3000

---

5️⃣ Crear un Evento de Prueba

En una tercera terminal, simula un evento:

Test: Checkout Completado

stripe trigger checkout.session.completed

Verás en la consola del servidor:

✓ [Webhook] Received checkout.session.completed
✓ Created subscription in DB

Test: Pago de Factura (Renovación)

stripe trigger invoice.payment_succeeded

Test: Pago Fallido

stripe trigger invoice.payment_failed

---

6️⃣ Verificar Eventos

En la terminal donde ejecutaste stripe listen:

2025-01-15 10:30:00 → checkout.session.completed
2025-01-15 10:30:01 → invoice.payment_succeeded

---

🔍 Debugging

Ver logs del webhook:

stripe logs tail

Ver eventos recientes en dashboard:

https://dashboard.stripe.com/test/webhooks

---

✅ Test Flow Completo

# Terminal 1: Webhook listener
stripe listen --forward-to localhost:3000/api/payments/webhook

# Terminal 2: Servidor
npm run dev

# Terminal 3: Triggear eventos
stripe trigger checkout.session.completed
stripe trigger invoice.payment_succeeded

# Ver resultados en BD:
npx prisma studio

---

💡 Tips

• Stripe CLI se desconecta automáticamente cada 1 hora
  • Ejecuta nuevamente: stripe listen --forward-to ...
• Los eventos triggados son reales (van a tu BD)
• No requiere tarjeta de crédito
• Los webhooks se reciben en tiempo real

---

¡Listo para testear! 🚀