# KamiPay PIX Integration - Guía de Instalación

## 📋 Resumen
Esta integración permite a los jugadores brasileños donar usando PIX, el sistema de pagos instantáneos de Brasil, a través de la API de KamiPay.

## 🚀 Características Implementadas
- ✅ Autenticación JWT con KamiPay API
- ✅ Generación de QR codes PIX dinámicos
- ✅ Página de pago con QR code y timer
- ✅ Verificación automática de estado de transacciones
- ✅ Sistema de webhooks para notificaciones instantáneas
- ✅ Interfaz multiidioma (ES/EN/PT)
- ✅ Validaciones de seguridad completas
- ✅ Logging detallado para debugging

## 📁 Archivos Creados/Modificados

### Nuevos Archivos:
```
kamipay/
├── KamiPayAPI.php          # Clase principal para interactuar con KamiPay API
├── pix_payment.php         # Página de pago PIX con QR code
├── check_status.php        # API para verificar estado de transacciones
├── webhook.php             # Endpoint para recibir notificaciones de KamiPay
├── database.sql            # Script SQL para crear tablas necesarias
└── INSTALLATION.md         # Esta guía
```

### Archivos Modificados:
- `configs.php` - Agregada configuración de KamiPay
- `don_save.php` - Agregado procesamiento de pagos KamiPay
- `donaciones.php` - Agregada interfaz PIX y traducciones

## 🔧 Configuración Paso a Paso

### 1. Crear Tablas de Base de Datos
Ejecutar el script SQL:
```sql
-- Ejecutar el contenido de kamipay/database.sql
```

### 2. Obtener Credenciales de KamiPay
Contactar a KamiPay para obtener:
- Username de desarrollo
- Password de desarrollo  
- Username de producción
- Password de producción
- Dirección de wallet USDT (debe estar en whitelist)

### 3. Configurar Credenciales
Editar `configs.php` y actualizar:
```php
// KamiPay (PIX Brasil)
$kamipay_mode = 0; // 0: Desarrollo, 1: Producción
$kamipay_username_dev = 'TU_USUARIO_DEV';
$kamipay_password_dev = 'TU_PASSWORD_DEV';
$kamipay_username_prod = 'TU_USUARIO_PROD';
$kamipay_password_prod = 'TU_PASSWORD_PROD';
$kamipay_wallet_address = 'TU_DIRECCION_WALLET_USDT';
```

### 4. Actualizar Clase KamiPayAPI
Editar `kamipay/KamiPayAPI.php` líneas 19-22:
```php
$this->username = $isDevelopment ? 'TU_USUARIO_DEV' : 'TU_USUARIO_PROD';
$this->password = $isDevelopment ? 'TU_PASSWORD_DEV' : 'TU_PASSWORD_PROD';
```

### 5. Configurar Webhook en KamiPay
Proporcionar a KamiPay la URL del webhook:
```
https://tudominio.com/panel/kamipay/webhook.php
```

### 6. Configurar Permisos
```bash
chmod 755 kamipay/
chmod 644 kamipay/*.php
chmod 666 kamipay_log.txt (crear archivo vacío)
chmod 666 kamipay_webhook.log (crear archivo vacío)
```

## 🧪 Testing

### Modo Desarrollo
1. Configurar `$kamipay_mode = 0` en `configs.php`
2. Usar credenciales de desarrollo
3. Los pagos se procesan en entorno de pruebas

### Verificar Funcionalidad
1. Ir a donaciones.php
2. Seleccionar método "PIX"
3. Verificar que aparezca la opción PIX
4. Intentar crear una transacción de prueba

### Logs de Debug
Verificar logs en:
- `kamipay_log.txt` - Logs de API
- `kamipay_webhook.log` - Logs de webhooks
- Error logs del servidor web

## 🔒 Seguridad Implementada

### Validaciones:
- ✅ Verificación de personaje existente
- ✅ Validación de montos mínimos (15 BRL)
- ✅ Sanitización de inputs
- ✅ Prepared statements SQL
- ✅ Verificación CSRF
- ✅ Expiración automática de transacciones

### Logging:
- ✅ Todas las transacciones se registran
- ✅ Webhooks se almacenan para auditoría
- ✅ Errores se logean con detalles

## 💰 Flujo de Pago PIX

1. **Usuario selecciona PIX** → Valida datos → Crea transacción
2. **Sistema obtiene cotización** → KamiPay Oracle API
3. **Genera QR PIX** → KamiPay Create Dynamic PIX
4. **Usuario paga** → Banco procesa PIX
5. **KamiPay notifica** → Webhook actualiza estado
6. **Sistema procesa** → Agrega JC al personaje

## 📊 Monitoreo

### Verificar Estado de Transacciones:
```sql
SELECT * FROM kamipay_transactions 
WHERE created_at > DATE_SUB(NOW(), INTERVAL 1 DAY)
ORDER BY created_at DESC;
```

### Verificar Webhooks:
```sql
SELECT * FROM kamipay_webhook_logs 
WHERE created_at > DATE_SUB(NOW(), INTERVAL 1 DAY)
ORDER BY created_at DESC;
```

### Transacciones Pendientes:
```sql
SELECT * FROM kamipay_transactions 
WHERE status IN ('pending', 'processing') 
AND expires_at > NOW();
```

## 🚨 Troubleshooting

### Error: "No se pudo obtener la cotización PIX"
- Verificar credenciales de KamiPay
- Verificar conectividad a internet
- Revisar logs en `kamipay_log.txt`

### Error: "Transacción no encontrada"
- Verificar que las tablas fueron creadas
- Verificar permisos de base de datos

### PIX no aparece como opción
- Verificar que se agregó 'kamipay' a `$metodos_permitidos`
- Verificar JavaScript de la página

### Webhooks no funcionan
- Verificar URL del webhook con KamiPay
- Verificar permisos del archivo webhook.php
- Revisar logs del servidor web

## 📞 Soporte

Para problemas técnicos:
1. Revisar logs detallados
2. Verificar configuración paso a paso
3. Contactar soporte de KamiPay si es necesario

## 🔄 Modo Producción

Para activar en producción:
1. Configurar `$kamipay_mode = 1`
2. Usar credenciales de producción
3. Verificar webhook URL
4. Hacer pruebas con montos pequeños
5. Monitorear logs inicialmente

---

**Nota**: Esta integración está lista para producción pero requiere configuración de credenciales reales de KamiPay.
