Financial (Payments & Subscriptions)

El módulo Financial gestiona el flujo de caja de la plataforma. Utiliza Stripe como procesador principal y soporta pagos con tarjeta, suscripciones mensuales y dispersión de fondos a vendedores vía Stripe Connect.

💸 Gestión de Pagos

1. Crear Intento de Pago (One-Time)

POST /api/v1/payments/intent

Role: VENDEDOR+

Genera un PaymentIntent en Stripe para cobrar el total de una póliza o una cuota específica.

Esquema de Petición (`CreatePaymentIntentRequest`)

policy_id: UUID de la póliza asociada.
payment_method_id: Opcional. ID de una tarjeta guardada previamente.
save_payment_method: Boolean. Si es true, la tarjeta se adjunta permanentemente al cliente en Stripe.

Respuesta de Éxito (`TransactionResponse`)

Retorna un client_secret. Este campo es obligatorio para que el frontend pueda completar la autenticación 3DS (SCA) mediante Stripe Elements.

2. Registro de Pago Manual (Offline)

POST /api/v1/payments/manual

Role: ADMIN

Permite registrar ingresos que no pasan por Stripe (ej. efectivo, transferencia bancaria directa).

Efecto: Crea una transacción con estado PAID vinculada a la póliza, disparando la activación de la misma si el monto cubre la prima.

🔁 Suscripciones Recurrentes

3. Crear Suscripción Mensual

POST /api/v1/payments/subscription

Role: VENDEDOR+

Inicia un cobro recurrente automático.

Configuración Actuarial

billing_anchor_day: Entero (1-28). Permite anclar el cobro a un día específico del mes (ej. todos los días 5). Si no se envía, se toma el día actual.

Códigos de Respuesta

201 Created: Suscripción activa en Stripe.
402 Payment Required: La tarjeta fue rechazada durante el primer cobro.

4. Cancelar Suscripción

POST /api/v1/payments/subscription/cancel

Role: ADMIN

Detiene los cobros recurrentes de una póliza.

cancel_immediately: Si es true, termina la cobertura al instante. Si es false, espera al final del periodo pagado.

🏦 Resellers y Comisiones (Stripe Connect)

5. Onboarding de Vendedor

POST /api/v1/payments/connect/onboarding

Auth Required

Genera un enlace temporal de Stripe para que el vendedor vincule su cuenta bancaria.

Response: Retorna una url a la cual el frontend debe redirigir al usuario para completar su perfil financiero.

📡 Webhooks (Eventos de Stripe)

POST /api/v1/payments/webhook Seguridad: Verifica la firma stripe-signature usando el secret del servidor.

El sistema procesa en segundo plano (BackgroundTasks) los siguientes eventos críticos:

invoice.paid: Marca la póliza como ACTIVE y genera el PDF.
invoice.payment_failed: Notifica al cliente y cambia el estado a PAID_FAILED.
customer.subscription.deleted: Se dispara cuando una suscripción expira o es cancelada desde el dashboard de Stripe.

📊 Consulta de Transacciones

GET /api/v1/payments/transactions

Lista el historial financiero. Permite filtrar por policy_id o status (PENDING, PAID, FAILED).