Saltar al contenido principal

Configuración de Stripe

Esta guía describe los pasos necesarios para preparar Stripe en cada entorno (desarrollo, staging, producción).

1. Crear Cuentas y Claves​

  1. Accede a tu Dashboard de Stripe
  2. Usa el modo Test para pruebas y Live para producción
  3. Genera:
    • STRIPE_SECRET_KEY (sk_live/sk_test) para el backend
    • STRIPE_PUBLISHABLE_KEY (pk_live/pk_test) para el frontend
  4. Guarda las claves en los .env correspondientes (backend/.env, frontend/.env)

2. Webhooks​

  1. En el Dashboard → Developers → Webhooks, crea un endpoint apuntando a:
    • https://api.tu-dominio.com/api/payments/webhooks/stripe
  2. Selecciona los eventos:
    • payment_intent.succeeded
    • payment_intent.payment_failed
    • payment_intent.canceled
  3. Copia el Signing secret (STRIPE_WEBHOOK_SECRET) y añádelo al .env del backend
  4. Para desarrollo local, utiliza stripe listen --forward-to localhost:8000/api/payments/webhooks/stripe para reenviar eventos

3. Stripe Connect (Opcional)​

Si utilizas cuentas Connect para pagar a expertos:

  1. Configura una cuenta Connect Express desde el Dashboard
  2. En Developers → Connect settings, define:
    • Return URL: https://app.tu-dominio.com/dashboard/experto?stripe=success (o la URL configurada en STRIPE_CONNECT_RETURN_URL)
    • Refresh URL: https://app.tu-dominio.com/dashboard/experto?stripe=refresh (o la URL configurada en STRIPE_CONNECT_REFRESH_URL)
  3. Copia el Client ID y añádelo como STRIPE_CONNECT_CLIENT_ID
  4. Ajusta las URLs en backend/.env (STRIPE_CONNECT_RETURN_URL, STRIPE_CONNECT_REFRESH_URL)

Nota: El sistema soporta dos tipos de enlaces:

  • Onboarding inicial: Para configurar la cuenta Connect por primera vez
  • Actualización de cuenta: Para modificar información bancaria, datos fiscales, etc.

4. Ajustes Adicionales​

  • Currency: la aplicación usa EUR como moneda por defecto; ajusta si es necesario
  • Fees / Escrow: el backend crea PaymentIntents con capture_method="manual". Debes capturar fondos cuando el hito sea aprobado
  • Dashboard enlaces: ProjectPayments utiliza VITE_STRIPE_DASHBOARD_URL_BASE para abrir pagos desde la UI; configúralo según test/live

5. Pruebas​

  1. Con el entorno en modo test, usa tarjetas de prueba (p.ej. 4242 4242 4242 4242)
  2. Verifica que los webhooks actualizan el estado de pagos/hitos
  3. Asegúrate de que los flujos Playwright pasan

6. Verificación en Producción​

  1. Desde el Dashboard de Stripe, en Developers → Webhooks, revisa que no haya eventos fallidos tras el despliegue
  2. Ejecuta nuestro script de verificación para enviar un payment_intent.succeeded de prueba y confirmar la firma
  3. Comprueba los logs del backend (docker compose logs backend) en busca de errores relacionados con Stripe
  4. En caso de fallo, verifica de nuevo el secreto (STRIPE_WEBHOOK_SECRET) y la URL configurada

7. Script de Verificación Local​

Puedes comprobar rápidamente la configuración usando la CLI de Stripe:

stripe trigger payment_intent.succeeded \
  --api-key $STRIPE_SECRET_KEY \
  --webhook-endpoint https://api.tu-dominio.com/api/payments/webhooks/stripe

Si quieres apuntar a staging/local con túnel, usa stripe listen y la URL correspondiente.

Checklist Rápido​

  • Claves secretas y públicas configuradas
  • Webhook creado y firmado
  • Stripe Connect (si aplica) con URLs correctas
  • Tarjetas de prueba verificadas
  • Captura manual probada (aprobar hito en la app)

Mantén las claves sensibles fuera del repositorio y rota los secretos periódicamente.

Más Información​