# Flujo de Pagos en el Wizard de Reservas

Este documento explica las **2 opciones de pago** que se ofrecen al cliente en el wizard de reservas.

---

## Visión general

Cuando un cliente completa los pasos 1-4 del wizard (fecha, toldo, extras, datos), llega al **Paso 5 — Pagar**, donde elige entre:

1. **💳 Pagar Ahora Online** — Pago Móvil con validación instantánea
2. **💬 Cotizar por WhatsApp** — Coordinar y pagar al llegar al sitio

---

## Flujo A: Pago Online (Pago Móvil)

### Paso a paso

```
1. Cliente termina Step 4 (datos personales)
       ↓
2. Click en "Pagar Ahora" en Step 5
       ↓
3. Sistema crea booking en DB con status=PENDING
       ↓
4. UI muestra:
   - Lado izquierdo: instrucciones de Pago Móvil (banco, RIF, teléfono, monto)
   - Lado derecho: form para validar (banco origen + referencia)
       ↓
5. Cliente abre su app del banco y hace el Pago Móvil
       ↓
6. Cliente vuelve y ingresa: banco origen + referencia
       ↓
7. Click "Validar Pago"
       ↓
8. Backend → POST /api/payments/movilpay/validate
       ↓
9. Sistema valida contra MovilPay API
       ↓
   ¿Válida?
   ├── SÍ → booking.status = PAID + email confirmación + animación de éxito
   └── NO → mensaje de error, cliente puede reintentar
```

### Modo desarrollo (sin credenciales reales)

Si `MOVILPAY_TOKEN` está vacío en `.env`, el sistema entra en **modo simulación**:
- Cualquier referencia con **6 o más dígitos** se considera válida.
- No se llama a la API real.
- Útil para probar el flujo en local sin tener credenciales.

### Modo producción

Cuando `MOVILPAY_TOKEN` está configurado:
- Cada validación llama a `POST {MOVILPAY_BASE_URL}/validate`
- Headers: `Authorization: Bearer {MOVILPAY_TOKEN}`
- Body: `{ reference, bank_code, amount, phone }`
- Respuesta esperada: `{ valid: true|false, gateway_id, error? }`

### Estados posibles

| Resultado | Status final | Acción |
|---|---|---|
| ✅ Válido | `PAID` | Email enviado, reserva confirmada |
| ❌ Referencia no encontrada | `PENDING` | Cliente puede reintentar |
| ❌ Monto no coincide | `PENDING` | Mensaje específico mostrando el monto correcto |
| ❌ Reserva ya pagada | — | Bloqueado, no se valida 2 veces |

---

## Flujo B: Cotización + Pago en Sitio

### Paso a paso

```
1. Cliente termina Step 4 (datos personales)
       ↓
2. Click en "Cotizar por WhatsApp" en Step 5
       ↓
3. Sistema crea booking en DB con status=PENDING
       ↓
4. Se abre WhatsApp con mensaje pre-armado conteniendo:
   - Datos del cliente
   - Detalles de la reserva
   - Total a pagar
   - Aviso "Pagar en el sitio"
       ↓
5. Cliente y admin coordinan por WhatsApp
       ↓
6. Día de la visita: cliente paga en el sitio
       ↓
7. Admin marca la reserva como PAID o CONFIRMED
   desde el panel admin manualmente.
```

### Cuándo conviene esta opción

- Cliente habitual que ya conoce al admin.
- Reservas grandes (eventos, paquetes especiales) que requieren cotización personalizada.
- Cliente sin acceso a Pago Móvil en ese momento.
- Pago en efectivo al llegar al club.

---

## Diagrama completo del flujo

```
                  ┌─────────────────────┐
                  │  Wizard Step 1-4    │
                  │  (datos completos)  │
                  └──────────┬──────────┘
                             ↓
                  ┌─────────────────────┐
                  │  Step 5: ¿Cómo pagar? │
                  └──┬───────────────┬──┘
                     │               │
              ┌──────▼─────┐   ┌────▼────────┐
              │ Pagar Online │   │  WhatsApp   │
              └──────┬─────┘   └────┬────────┘
                     │               │
          [crea booking PENDING]  [crea booking PENDING]
                     │               │
              ┌──────▼─────┐         │
              │Form Pago   │         ↓
              │Móvil + Ref │   ┌─────────────┐
              └──────┬─────┘   │ Abrir WA    │
                     │         │ con mensaje │
              [validate API]   └─────┬───────┘
                     │               │
            ┌────────┴────────┐      │
            ↓                 ↓      ↓
         ✅ PAID           ❌ Error  📱 PENDING
       (auto enviado     (reintentar) (espera admin)
        email confirm)
```

---

## Estados de booking según método

| Método elegido | Status inicial | paymentMethod | Validación |
|---|---|---|---|
| Online (validado) | `PAID` | `MOVILPAY` | Automática |
| Online (reintentando) | `PENDING` | `MOVILPAY` | Pendiente |
| WhatsApp | `PENDING` | `null` (se asigna después) | Manual desde admin |

> Nota: cuando el cliente eligió "Online" y aún no validó, el booking queda con `paymentMethod=null` hasta que se valide. Si el cliente abandona, queda como reserva pendiente. El admin puede igual contactarlo y procesar el pago manualmente.

---

## Implementación técnica

### Archivos involucrados

```
app/
├── api/
│   ├── bookings/route.js                    # POST: crea reserva
│   └── payments/
│       └── movilpay/
│           └── validate/route.js            # POST: valida referencia
├── components/
│   └── ReservaWizard.jsx                    # UI del wizard con Step 5
lib/
├── movilpay.js                              # Cliente MovilPay (real o simulado)
├── validators.js                            # validatePaymentSchema
└── email.js                                 # sendBookingConfirmation
```

### Variables de entorno relevantes

```env
# Producción real:
MOVILPAY_TOKEN="re_xxxxxxxxxxxxx"
MOVILPAY_BASE_URL="https://api.movilpay.com.ve"

# Datos visibles al cliente:
NEXT_PUBLIC_PAGOMOVIL_BANK="Banesco"
NEXT_PUBLIC_PAGOMOVIL_RIF="J-XXXXXXXXX-X"
NEXT_PUBLIC_PAGOMOVIL_PHONE="0424-1574708"
```

---

## ¿Cómo cambiar las credenciales de Pago Móvil?

Cuando recibas tu token de MovilPay:

1. Edita `.env`:
   ```env
   MOVILPAY_TOKEN="tu_token_real"
   MOVILPAY_BASE_URL="https://api.movilpay.com.ve"
   ```

2. Reinicia el servidor (`Ctrl+C` y `npm run dev` de nuevo).

3. A partir de ahí, el sistema valida contra la API real. Las referencias inventadas **ya no funcionarán** en sandbox.

### Antes de ir a producción

Verifica:
- ✅ El RIF y teléfono de Pago Móvil mostrados al cliente son los correctos.
- ✅ El token de MovilPay es de producción (no sandbox).
- ✅ El banco principal del receptor coincide con `NEXT_PUBLIC_PAGOMOVIL_BANK`.
- ✅ Las pruebas con monto chico (ej: $1) funcionaron.

---

## Casos especiales

### "El cliente pagó pero la referencia no valida"

Posibles causas:
1. El cliente escribió la referencia mal (intercambió dígitos).
2. El monto no coincide (cliente pagó otra cantidad).
3. La referencia es de hace tiempo (> 24 horas, MovilPay puede no encontrarla).

**Solución**: el admin puede marcar manualmente la reserva como PAID desde el panel, después de verificar el pago en el banco.

### "El cliente cerró la pantalla antes de validar"

La reserva queda en `PENDING`. El admin la verá en `/admin/pagos` y puede:
- Contactar por WhatsApp para que vuelva a validar.
- Validarla manualmente si ya verificó el pago.
- Cancelarla si el cliente no responde en 24h.

### "La validación falla con error técnico"

Si la API de MovilPay está caída, el endpoint retorna 500. El cliente verá el mensaje genérico "Error de conexión con MovilPay". Recomendar usar el flujo de WhatsApp como fallback.

---

## Métricas a monitorear

Una vez en producción, observar:

1. **Tasa de conversión Online vs WhatsApp**: ¿qué % de clientes elige cada método?
2. **Tasa de éxito en validación**: ¿qué % de pagos online se validan al primer intento?
3. **Tiempo promedio en Step 5**: si pasan demasiado tiempo, puede haber confusión en las instrucciones.
4. **Reservas PENDING > 24h**: indicador de abandonos.

Con esto puedes optimizar el flujo (mejorar instrucciones, ajustar bancos disponibles, etc.).
