# Integración de Pasarelas de Pago — Plan Roadmap

Este documento describe cómo evolucionará el sistema de pagos del Club VIP Los Caracas.

---

## Estado actual: Fase 1 (Manual con WhatsApp)

**Cómo funciona ahora**:

1. Cliente completa el wizard de reserva en el sitio.
2. Click en "Enviar por WhatsApp".
3. La reserva se guarda en MySQL en estado **PENDING**.
4. Se abre WhatsApp con un mensaje pre-armado al cliente.
5. El cliente paga por su lado (Pago Móvil, transferencia, etc.).
6. El cliente envía la referencia por WhatsApp.
7. **Admin registra el pago manualmente** en el panel.
8. Reserva pasa a **PAID**.

**Ventajas**:
- Cero dependencias de pasarelas pagas.
- Cero complejidad técnica.
- Funciona desde el día 1.

**Desventajas**:
- Requiere validación humana.
- Posibilidad de error humano (referencias falsas).
- No escala más allá de ~50 reservas/día.

---

## Fase 2: Pago Móvil con validación automática

**Objetivo**: cuando el cliente complete la reserva, se le muestren las instrucciones de pago, y al ingresar la referencia el sistema **valide automáticamente** contra la API de MovilPay sin intervención humana.

### Flujo nuevo

```
Cliente completa wizard (4 pasos)
       ↓
[NUEVO] Paso 5: Instrucciones de Pago Móvil
       ↓
Cliente paga en su app del banco
       ↓
[NUEVO] Cliente ingresa referencia + banco
       ↓
Frontend → POST /api/payments/movilpay/validate
       ↓
Backend valida contra API de MovilPay
       ↓
   ¿Válida?
   ├── SÍ → Booking pasa a PAID automáticamente + email confirmación
   └── NO → Mensaje de error, cliente puede reintentar
```

### Qué hay que construir

#### 1. Adaptar `lib/movilpay.js`

Tomar el archivo `movilpay-client.ts` de la documentación e integrarlo:

```js
// lib/movilpay.js
const MOVILPAY_TOKEN = process.env.MOVILPAY_TOKEN;
const MOVILPAY_BASE_URL = process.env.MOVILPAY_BASE_URL;

export async function validateMovilPayReference({ reference, bank, amount, phone }) {
  // POST a https://api.movilpay.com.ve/validate
  // con headers Authorization: Bearer {MOVILPAY_TOKEN}
  // body { reference, bank_code, amount, phone }

  // Retorna { valid: true|false, gateway_id, error?: string }
}
```

#### 2. API route `/api/payments/movilpay/validate`

```js
// app/api/payments/movilpay/validate/route.js
import { validateMovilPayReference } from "@/lib/movilpay";
import { prisma } from "@/lib/db";
import { validatePaymentSchema } from "@/lib/validators";

export async function POST(req) {
  const body = await req.json();
  const { bookingId, reference, bank, amount } = validatePaymentSchema.parse(body);

  // 1. Buscar booking
  const booking = await prisma.booking.findUnique({ where: { id: bookingId } });
  if (!booking) return Response.json({ error: "Reserva no existe" }, 404);
  if (booking.status !== "PENDING") return Response.json({ error: "Ya pagada" }, 400);

  // 2. Validar monto
  if (Number(booking.total) !== amount) return Response.json({ error: "Monto no coincide" }, 400);

  // 3. Validar contra MovilPay
  const result = await validateMovilPayReference({
    reference,
    bank,
    amount,
    phone: booking.customerPhone,
  });

  if (!result.valid) {
    return Response.json({ error: result.error || "Referencia inválida" }, 400);
  }

  // 4. Actualizar booking
  await prisma.booking.update({
    where: { id: bookingId },
    data: {
      status: "PAID",
      paymentMethod: "MOVILPAY",
      paymentRef: reference,
      paymentBank: bank,
      paymentDate: new Date(),
    },
  });

  return Response.json({ success: true });
}
```

#### 3. Nuevo paso en el wizard

Agregar **Step 5 — Pago** entre Step 4 (datos) y la confirmación:

```jsx
{step === 5 && (
  <PaymentStep
    bookingId={bookingId}
    total={total}
    onSuccess={() => setStep(6)}
  />
)}
```

El componente `PaymentStep` muestra:
- Las instrucciones de Pago Móvil (banco, RIF, teléfono receptor, monto).
- Un campo para ingresar la referencia.
- Un select de banco origen.
- Botón "Validar pago" que llama al API.

#### 4. Variables de entorno

```env
MOVILPAY_TOKEN="proporcionado_por_movilpay"
MOVILPAY_BASE_URL="https://api.movilpay.com.ve"
NEXT_PUBLIC_PAGOMOVIL_BANK="Banesco"
NEXT_PUBLIC_PAGOMOVIL_RIF="J-XXXXXXXXX-X"
NEXT_PUBLIC_PAGOMOVIL_PHONE="0424-1574708"
```

### Tiempo estimado

- Setup MovilPay account: 1-2 días (proceso del proveedor)
- Implementación técnica: **3-4 horas**
- Testing y ajustes: 2 horas
- **Total**: ~1 semana incluyendo coordinación con MovilPay

### Pre-requisitos

- ✅ Cuenta de comercio en MovilPay (https://movilpay.com.ve)
- ✅ Token API
- ✅ RIF y banco receptor activos

---

## Fase 3: BDV C2P (Débito inmediato)

**Diferencia clave con Pago Móvil**: el cliente NO paga primero por su lado. El pago ocurre **dentro del wizard** mediante OTP del Banco de Venezuela.

### Flujo

```
Cliente en Step 5
       ↓
Ingresa: cédula, banco, teléfono
       ↓
Backend → BDV C2P API: solicitar OTP
       ↓
BDV envía OTP por SMS al cliente
       ↓
Cliente ingresa OTP (30s máximo)
       ↓
Backend → BDV C2P API: confirmar débito
       ↓
   ¿Aprobado?
   ├── SÍ → débito hecho + booking PAID
   └── NO → mensaje de error
```

### Ventaja: confirmación instantánea (10-15 segundos)

### Tiempo estimado: 5-7 horas + coordinación con BDV

---

## Fase 4: Stripe (tarjetas internacionales)

Para turistas, expatriados, o pagos en USD desde el exterior.

### Flujo

- Stripe Elements embebido en el wizard.
- Cliente ingresa tarjeta + CVV.
- Stripe procesa el pago.
- Webhook a `/api/payments/stripe/webhook` confirma.

### Tiempo estimado: 3-4 horas

---

## Comparativa de métodos

| Método | Velocidad | Setup | Comisión típica | Mejor para |
|---|---|---|---|---|
| WhatsApp manual | Lento (horas) | 0 min | 0% | MVP / volumen bajo |
| Pago Móvil | Medio (validación auto) | 1 sem | ~1% | Operación normal |
| BDV C2P | Instantáneo | 1-2 sem | ~1.5% | Conversion-critical |
| Stripe | Instantáneo | 1 día | 2.9% + $0.30 | Internacional |

---

## ¿Cuál implementar primero?

**Recomendación**: empieza con **Pago Móvil** (Fase 2) porque:

1. Es el método más usado en Venezuela (>70% de reservas).
2. Setup relativamente rápido.
3. Comisión baja.
4. UX aceptable: el cliente ya está pagando con su banco habitual.

Dejá BDV C2P para después, cuando quieras optimizar la conversión y reducir el "abandono" entre reservar y pagar.

Stripe sólo si tu público objetivo incluye turistas (cuál es probablemente algo a futuro).

---

## Costos estimados mensuales (referencia)

Sobre 100 reservas/mes con ticket promedio de $50:

| Método | Volumen | Comisión total/mes |
|---|---|---|
| Pago Móvil | 70 reservas × $50 × 1% | $35 |
| BDV C2P | 20 reservas × $50 × 1.5% | $15 |
| Stripe | 10 reservas × $50 × 2.9% + $0.30 | $17.5 |

Total mensual: **~$67** en comisiones por **$5,000 de revenue**. Aceptable.

---

## Referencias

- Documentación original en `C:\Users\Moises\Desktop\Integracion`
- MovilPay: https://movilpay.com.ve
- BDV C2P: contactar al banco directamente
- Stripe: https://stripe.com/docs
