Checkout y Pagos

1. Definicion y proposito

Convertir una intencion de cita en reserva confirmada con trazabilidad de pago.

Pasarela principal: Recurrente por compatibilidad bancaria de la organizacion.

2. Reglas de negocio

• Idempotencia obligatoria en confirmacion de pago.
• La cita solo se confirma al estado paid o authorized segun politica.
• Reversas/errores de pago deben liberar slot automaticamente.
• order_id unico por intento de checkout; no reutilizar entre sesiones.
• El frontend redirige al checkout_url devuelto por Recurrente; la fuente de verdad final es el webhook.

3. Endpoints propuestos

Recurso	Metodo	Descripcion	Rol
/api/v1/checkout/quote	POST	Calcula total (tarifa, descuentos, recargos).	PATIENT
/api/v1/checkout/recurrente/create	POST	Crea checkout en Recurrente y devuelve checkout_url.	PATIENT
/api/v1/payments/webhook/recurrente	POST	Callback firmado de Recurrente.	Sistema
/api/v1/payments/test-recurrente	GET	Healthcheck de conexion con Recurrente (solo no-prod).	SUPERADMIN

4. Campos minimos

• appointment_draft_id, amount, currency.
• coupon_code opcional.
• customer (email, nombre, telefono) para checkout.
• metadata con order_id, appointment_id, user_id.
• payment_method_token (nunca PAN crudo) cuando aplique.

5. Seguridad

• Cumplimiento PCI por tokenizacion con pasarela.
• Webhook firmado y validado con headers svix-id, svix-timestamp, svix-signature.
• No exponer datos de tarjeta ni secretos en logs.
• Verificar firma con RECURRENTE_WEBHOOK_SECRET; rechazar payload sin firma.
• Procesamiento idempotente de webhook por event_id/order_id.

6. Trazabilidad

• Relacionado con agenda-citas.md, cupones-promociones.md, notificaciones.md.

7. Variables de entorno (pasarela)

• RECURRENTE_PUBLIC_KEY
• RECURRENTE_SECRET_KEY
• RECURRENTE_WEBHOOK_SECRET