# ⚽ Configuración de Pasarela de Pago - App de Fútbol Torino

## 🎯 Objetivo
Configurar Culqi como pasarela de pago para procesar donaciones, membresías, entradas a partidos, y otros pagos relacionados con el fútbol.

## 📋 Requisitos Previos

### 1. Actualizar PHP (OBLIGATORIO)
```bash
# Verificar versión actual
php -v

# Si tienes PHP 7.4, necesitas actualizar a 8.2+
# En Windows con Laragon:
# 1. Descargar Laragon con PHP 8.2+ desde https://laragon.org/download/
# 2. Instalar y configurar
# 3. Reiniciar Laragon

# En Linux:
sudo apt update
sudo apt install php8.2 php8.2-cli php8.2-common php8.2-mysql php8.2-zip php8.2-gd php8.2-mbstring php8.2-curl php8.2-xml php8.2-bcmath
```

### 2. Verificar Composer
```bash
composer --version
# Si no está instalado: https://getcomposer.org/download/
```

## 🚀 Pasos de Configuración

### Paso 1: Instalar Dependencias
```bash
# Navegar al proyecto
cd C:\laragon\www\torino

# Instalar Culqi PHP SDK
composer require culqi/culqi-php

# Limpiar caché
php artisan config:clear
php artisan cache:clear
```

### Paso 2: Crear Cuenta en Culqi
1. **Ir a**: https://culqi.com
2. **Hacer clic en**: "Registrarse"
3. **Completar formulario** con datos de tu club/empresa
4. **Verificar email**
5. **Completar verificación de negocio**

### Paso 3: Obtener Credenciales de Culqi

#### En el Panel de Culqi:
1. **Iniciar sesión** en tu cuenta
2. **Ir a**: Configuración > API Keys
3. **Copiar**:
   - **Public Key** (empieza con `pk_test_` o `pk_live_`)
   - **Secret Key** (empieza con `sk_test_` o `sk_live_`)

#### Configurar Webhooks:
1. **Ir a**: Configuración > Webhooks
2. **Hacer clic en**: "Agregar Webhook"
3. **URL**: `https://tu-dominio.com/webhook/culqi`
4. **Eventos a escuchar**:
   - ✅ `charge.succeeded`
   - ✅ `charge.failed`
   - ✅ `charge.expired`
5. **Copiar** el **Webhook Secret** (empieza con `whsec_`)

### Paso 4: Configurar Variables de Entorno

#### Crear archivo `.env`:
```env
# ========================================
# CONFIGURACIÓN DE LARAVEL
# ========================================
APP_NAME="Torino FC - Sistema de Pagos"
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

# ========================================
# BASE DE DATOS
# ========================================
DB_CONNECTION=sqlite
DB_DATABASE=C:\laragon\www\torino\database\database.sqlite

# ========================================
# CONFIGURACIÓN DE CULQI
# ========================================
CULQI_PUBLIC_KEY=pk_test_tu_public_key_aqui
CULQI_SECRET_KEY=sk_test_tu_secret_key_aqui
CULQI_ENVIRONMENT=development
CULQI_WEBHOOK_SECRET=whsec_tu_webhook_secret_aqui
CULQI_CURRENCY=PEN

# ========================================
# CONFIGURACIÓN DE LA APP DE FÚTBOL
# ========================================
CLUB_NAME="Torino FC"
CLUB_EMAIL="admin@torinofc.com"
CLUB_PHONE="+51 123 456 789"

# ========================================
# OTRAS CONFIGURACIONES
# ========================================
LOG_CHANNEL=stack
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=debug

BROADCAST_DRIVER=log
CACHE_DRIVER=file
FILESYSTEM_DISK=local
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120

MEMCACHED_HOST=127.0.0.1

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="noreply@torinofc.com"
MAIL_FROM_NAME="${APP_NAME}"

VITE_APP_NAME="${APP_NAME}"
```

### Paso 5: Generar Clave de Aplicación
```bash
php artisan key:generate
```

### Paso 6: Ejecutar Migraciones
```bash
php artisan migrate
```

### Paso 7: Crear Datos de Prueba
```bash
php artisan db:seed
```

## 🧪 Testing de la Integración

### Tarjetas de Prueba para Desarrollo:
```
VISA: 4111111111111111
MASTERCARD: 5555555555554444
AMEX: 378282246310005
Fecha: Cualquier fecha futura
CVV: Cualquier número de 3-4 dígitos
```

### Probar Diferentes Escenarios:
1. **Pago exitoso**: Usar tarjetas válidas
2. **Pago rechazado**: Usar tarjetas con fondos insuficientes
3. **Tarjeta expirada**: Usar fechas pasadas
4. **CVV incorrecto**: Usar CVV inválido

## 🔧 Configuración para Producción

### 1. Cambiar a Modo Producción:
```env
CULQI_ENVIRONMENT=production
CULQI_PUBLIC_KEY=pk_live_tu_public_key_produccion
CULQI_SECRET_KEY=sk_live_tu_secret_key_produccion
APP_ENV=production
APP_DEBUG=false
```

### 2. Configurar HTTPS:
- **Obligatorio** para Culqi en producción
- **Configurar SSL** en tu servidor web
- **Actualizar URL** del webhook a tu dominio de producción

### 3. Configurar Webhook de Producción:
- **URL**: `https://tu-dominio.com/webhook/culqi`
- **Verificar** que sea accesible desde internet
- **Probar** con eventos de prueba

## 📱 Métodos de Pago Soportados

### 1. Tarjetas de Crédito/Débito:
- ✅ Visa
- ✅ Mastercard
- ✅ American Express
- ✅ Diners Club

### 2. Billeteras Digitales:
- ✅ Yape (Perú)
- ✅ Plin (Perú)
- ✅ Agora Pay (Perú)

### 3. Transferencias Bancarias:
- ✅ PagoEfectivo
- ✅ Banca por Internet

## 🎮 Casos de Uso para App de Fútbol

### 1. Donaciones:
- Donaciones a la fundación del club
- Apoyo a categorías menores
- Proyectos sociales

### 2. Membresías:
- Membresía anual
- Membresía premium
- Acceso a beneficios exclusivos

### 3. Entradas:
- Entradas a partidos
- Abonos de temporada
- Entradas VIP

### 4. Merchandising:
- Camisetas oficiales
- Accesorios del club
- Productos conmemorativos

### 5. Servicios:
- Estacionamiento
- Alimentación
- Tours del estadio

## 🔒 Seguridad

### Mejores Prácticas:
1. **NUNCA** compartir Secret Keys
2. **SIEMPRE** usar HTTPS en producción
3. **VERIFICAR** firmas de webhooks
4. **MANTENER** dependencias actualizadas
5. **LOGEAR** todas las transacciones
6. **VALIDAR** datos de entrada
7. **USAR** tokens en lugar de datos de tarjeta

### Configuración de Seguridad:
```php
// En config/culqi.php
'security' => [
    'verify_webhook_signature' => true,
    'log_all_transactions' => true,
    'validate_input_data' => true,
    'use_https_only' => env('APP_ENV') === 'production',
],
```

## 📊 Monitoreo y Logs

### Verificar Logs:
```bash
# Logs de Laravel
tail -f storage/logs/laravel.log

# Logs específicos de Culqi
tail -f storage/logs/culqi.log

# Logs de errores
tail -f storage/logs/error.log
```

### Dashboard de Culqi:
- **Monitorear** transacciones en tiempo real
- **Verificar** webhooks recibidos
- **Analizar** reportes de ventas
- **Configurar** alertas

## 🚨 Solución de Problemas

### Error: "PHP version >= 8.2.0 required"
```bash
# Actualizar PHP a 8.2+
# Verificar instalación
php -v
```

### Error: "Culqi.publicKey is not set"
```bash
# Verificar configuración
php artisan config:clear
php artisan cache:clear

# Verificar .env
echo $CULQI_PUBLIC_KEY
```

### Error: "Invalid API key"
```bash
# Verificar claves en .env
# Asegurar que sean correctas
# Usar claves de test para desarrollo
```

### Webhook no funciona:
```bash
# Verificar URL accesible
# Usar ngrok para testing local
# Verificar logs
tail -f storage/logs/laravel.log
```

## 📞 Soporte

### Recursos Útiles:
- **Documentación Culqi**: https://docs.culqi.com
- **API Reference**: https://docs.culqi.com/api
- **Soporte Culqi**: support@culqi.com
- **Comunidad**: https://community.culqi.com

### Contacto de Emergencia:
- **Soporte Técnico**: +51 1 123 4567
- **Email**: soporte@torinofc.com
- **WhatsApp**: +51 999 888 777

## ✅ Checklist de Configuración

- [ ] PHP actualizado a 8.2+
- [ ] Composer instalado
- [ ] Culqi PHP SDK instalado
- [ ] Cuenta de Culqi creada
- [ ] API Keys obtenidas
- [ ] Webhook configurado
- [ ] Archivo .env configurado
- [ ] Migraciones ejecutadas
- [ ] Testing realizado
- [ ] HTTPS configurado (producción)
- [ ] Logs configurados
- [ ] Seguridad implementada

## 🎉 ¡Listo para Usar!

Una vez completada la configuración, tu app de fútbol estará lista para procesar pagos de forma segura y confiable con Culqi.

¿Necesitas ayuda con algún paso específico?