Guía técnica para implementar correctamente la facturación recurrente, cambios de plan, cancelaciones y reintentos de cobro en un backend de suscripciones. Cubre integración con Stripe, webhooks y estados del ciclo de vida.
Cuándo usarlo: Implementar billing recurrente seguro y resiliente
Herramienta recomendada: Claude
Actúa como un ingeniero de backend senior especializado en sistemas de pagos y facturación recurrente para plataformas SaaS. Tienes experiencia profunda con Stripe, webhooks, máquinas de estado y diseño de sistemas resilientes para billing. Necesito tu ayuda para implementar correctamente el sistema de billing de suscripciones en mi aplicación. Este es uno de los componentes más críticos del negocio y los errores aquí tienen consecuencias directas en revenue y experiencia del cliente. **Arquitectura del sistema de suscripciones:** Explica cómo modelar correctamente la base de datos para soportar: - Múltiples planes con diferentes ciclos de facturación (mensual, anual, trimestral) - Cambios de plan (upgrade y downgrade) con prorratio correcto - Períodos de prueba gratuita y su transición a pago - Descuentos, cupones y precios especiales para ciertos clientes - Historial de facturas y recibos accesibles para el cliente **Integración con Stripe (o proveedor equivalente):** Detalla el flujo técnico correcto para: - Crear un Customer y un PaymentMethod de forma segura - Configurar una Subscription con trial_end, proration_behavior y billing_cycle_anchor - Manejar el flujo de SCA/3DS (Strong Customer Authentication) para mercados europeos - Implementar Stripe Customer Portal para que los clientes gestionen sus datos de pago - Configurar correctamente el retry schedule para pagos fallidos (dunning) **Gestión de webhooks de forma resiliente:** Los webhooks son el corazón del billing asíncrono. Explica cómo: - Registrar y verificar la firma de webhooks (Stripe-Signature) - Diseñar un sistema idempotente para procesar eventos duplicados - Manejar los eventos críticos: invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted, customer.subscription.updated - Implementar una cola de procesamiento con reintentos y dead letter queue - Sincronizar el estado local de la suscripción con el estado en Stripe **Máquina de estados del ciclo de vida del suscriptor:** Define los estados posibles de una suscripción y las transiciones válidas: - trialing → active (tras pago exitoso al final del trial) - active → past_due (pago fallido) - past_due → active (pago recuperado) o canceled (dunning agotado) - active → canceled (cancelación voluntaria) - canceled → active (reactivación) **Manejo de casos edge críticos:** Describe cómo manejar correctamente: - Cambio de plan a mitad del ciclo de facturación y cálculo del prorratio - Cancelación al final del período vs. cancelación inmediata - Pausas de suscripción (pause_collection en Stripe) - Clientes con múltiples suscripciones activas - Migración de usuarios existentes a un nuevo plan sin interrupciones **Formato de respuesta:** 1. Diagrama de modelo de datos (tablas: users, subscriptions, plans, invoices, payment_methods) 2. Flujo técnico de activación de suscripción de principio a fin (pseudocódigo o código real) 3. Lista de webhooks de Stripe que debo manejar y qué hace cada uno 4. Checklist de seguridad para sistemas de billing 5. Errores comunes que cometen los equipos al implementar billing y cómo evitarlos Incluye ejemplos de código en el lenguaje que yo especifique si te lo pido.