wallabicher/PAYMENTS.md

Sistema de Pagos con Stripe

Este documento explica cómo configurar y usar el sistema de pagos integrado con Stripe en Wallabicher.

Configuración

1. Crear cuenta de Stripe

1. Visita https://stripe.com y crea una cuenta
2. Accede al Dashboard de Stripe
3. Obtén tus claves API desde: Developers → API keys

2. Configurar variables de entorno

Crea un archivo .env en /web/backend/ con las siguientes variables:

# Stripe Configuration
STRIPE_SECRET_KEY=sk_test_xxxxx  # Tu clave secreta de Stripe
STRIPE_WEBHOOK_SECRET=whsec_xxxxx  # Secret del webhook (ver paso 3)
BASE_URL=http://localhost  # URL base de tu aplicación

3. Configurar Webhooks de Stripe

Los webhooks son necesarios para que Stripe notifique a tu aplicación sobre eventos de pago:

1. Ve a Developers → Webhooks en el Dashboard de Stripe
2. Haz clic en "Add endpoint"
3. URL del endpoint: https://tu-dominio.com/api/payments/webhook
4. Selecciona los siguientes eventos:
   • checkout.session.completed
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
5. Copia el "Signing secret" (whsec_xxxxx) y agrégalo a STRIPE_WEBHOOK_SECRET

4. Configurar productos y precios en Stripe (Opcional)

El sistema crea automáticamente los productos y precios en Stripe si no existen, pero puedes crearlos manualmente:

Productos:

• Wallabicher Básico
• Wallabicher Pro
• Wallabicher Enterprise

Precios:

• Cada producto debe tener precios mensual y anual
• Los lookup_key deben seguir el formato: {planId}_{billingPeriod} (ej: basic_monthly, pro_yearly)

5. Actualizar Docker Compose

Descomenta las variables de Stripe en docker-compose.yml:

environment:
  - STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY}
  - STRIPE_WEBHOOK_SECRET=${STRIPE_WEBHOOK_SECRET}
  - BASE_URL=${BASE_URL:-http://localhost}

Luego crea un archivo .env en la raíz del proyecto:

STRIPE_SECRET_KEY=sk_test_xxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxx
BASE_URL=https://tu-dominio.com

Flujo de registro y pago

1. Registro de usuario

Los usuarios pueden registrarse desde la landing page o directamente en /dashboard/register:

1. Usuario selecciona un plan
2. Completa el formulario de registro (usuario, email, contraseña)
3. Si es plan gratuito:
   • Se crea la cuenta inmediatamente
   • Redirige al dashboard
4. Si es plan de pago:
   • Se crea la cuenta
   • Se inicia sesión automáticamente
   • Redirige a Stripe Checkout

2. Checkout de Stripe

En Stripe Checkout el usuario:

• Ingresa información de tarjeta
• Confirma el pago
• Es redirigido de vuelta al dashboard

3. Gestión de suscripción

Desde /dashboard/subscription el usuario puede:

• Ver su plan actual y límites
• Ver uso de búsquedas
• Cambiar de plan
• Cancelar suscripción
• Reactivar suscripción cancelada
• Gestionar método de pago (portal de Stripe)

Endpoints API

Pagos

• POST /api/payments/create-checkout-session - Crear sesión de checkout
• POST /api/payments/create-portal-session - Abrir portal de cliente
• POST /api/payments/cancel-subscription - Cancelar suscripción
• POST /api/payments/reactivate-subscription - Reactivar suscripción
• POST /api/payments/webhook - Webhook de Stripe (sin autenticación)

Usuarios

• POST /api/users/register - Registro público
• POST /api/users/login - Iniciar sesión
• POST /api/users/logout - Cerrar sesión
• GET /api/users/me - Información del usuario actual

Suscripciones

• GET /api/subscription/plans - Obtener planes disponibles
• GET /api/subscription/me - Obtener suscripción actual
• PUT /api/subscription/me - Actualizar suscripción

Límites de planes

Los límites se aplican automáticamente mediante middleware:

Plan Gratuito

• 2 búsquedas simultáneas
• Solo Wallapop
• 50 notificaciones/día

Plan Básico (€9.99/mes)

• 5 búsquedas simultáneas
• Wallapop + Vinted
• 200 notificaciones/día

Plan Pro (€19.99/mes)

• 15 búsquedas simultáneas
• Todas las plataformas
• 1000 notificaciones/día

Plan Enterprise (€49.99/mes)

• Búsquedas ilimitadas
• Todas las plataformas
• Notificaciones ilimitadas

Modo de prueba vs Producción

Modo de prueba (Desarrollo)

Usa claves de prueba (sk_test_xxxxx):

• No se procesan pagos reales
• Usa tarjetas de prueba: 4242 4242 4242 4242
• Los webhooks requieren Stripe CLI o túnel (ngrok)

Para probar webhooks localmente:

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

Modo producción

1. Obtener claves LIVE de Stripe

1. Ve a https://dashboard.stripe.com/apikeys (modo LIVE)
2. Copia la clave secreta sk_live_...
3. ¡IMPORTANTE! Nunca hagas commit de esta clave a git

2. Configurar webhook en Stripe Dashboard

1. Ve a https://dashboard.stripe.com/webhooks (modo LIVE)

2. Click en "Add endpoint"

3. Endpoint URL: Tu dominio + la ruta del webhook

   https://tudominio.com/api/payments/webhook
   

   Ejemplos:

   • https://wallabag.midominio.com/api/payments/webhook
   • https://api.miapp.com/api/payments/webhook

4. Selecciona estos eventos:

   • checkout.session.completed
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed

5. Guarda y copia el Webhook signing secret (whsec_...)

3. Variables de entorno en tu servidor

Docker Compose (VPS/servidor propio):

# En tu servidor, edita .env
STRIPE_SECRET_KEY=sk_live_TU_CLAVE_REAL
STRIPE_WEBHOOK_SECRET=whsec_SECRET_DEL_WEBHOOK
BASE_URL=https://tudominio.com

# Reinicia los contenedores
docker-compose restart backend

Heroku:

heroku config:set STRIPE_SECRET_KEY=sk_live_...
heroku config:set STRIPE_WEBHOOK_SECRET=whsec_...
heroku config:set BASE_URL=https://tu-app.herokuapp.com

Railway/Render/Vercel: Añade las variables en el panel de configuración del servicio.

4. ⚠️ Requisitos obligatorios

• HTTPS habilitado (Stripe requiere HTTPS en producción)
• Certificado SSL válido
• Dominio accesible públicamente

Seguridad

• Las claves de Stripe NUNCA deben exponerse en el frontend
• Los webhooks verifican la firma automáticamente
• Las rutas de pago requieren autenticación (excepto webhook)
• Los administradores pueden gestionar suscripciones de todos los usuarios

Troubleshooting

Los webhooks no funcionan

1. Verifica que STRIPE_WEBHOOK_SECRET esté configurado
2. Verifica que la URL del webhook en Stripe sea correcta
3. En desarrollo, usa stripe listen para reenviar webhooks
4. Revisa los logs en Stripe Dashboard → Developers → Webhooks

Los pagos no se reflejan

1. Verifica que el webhook esté recibiendo eventos
2. Verifica logs del backend para errores
3. Verifica que los metadatos (userId, planId) se estén enviando correctamente

Error "Stripe no está configurado"

• Verifica que STRIPE_SECRET_KEY esté en variables de entorno
• Reinicia el servidor backend después de configurar

Recursos

• Documentación de Stripe
• Stripe Checkout
• Stripe Webhooks
• Stripe CLI