> For the complete documentation index, see [llms.txt](https://gubo.gitbook.io/gubo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gubo.gitbook.io/gubo-docs/engagement/donations.md).

# Donations Plugin

El plugin de Donaciones permite a tu comunidad apoyarte económicamente y recibir recompensas automáticas en forma de coins del sistema de economía.

***

## 📑 Contenido

* [Características Principales](#caracteristicas-principales)
* [Plataformas Soportadas](#plataformas-soportadas)
* [Configuración para Usuarios](#configuracion-para-usuarios)
* [Cómo Donar](#como-donar)
* [Sistema de Recompensas](#sistema-de-recompensas)
* [Panel de Donaciones](#panel-de-donaciones)
* [Exchange Rates](#exchange-rates)
* [Configuración](#configuracion)
* [Seguridad y Privacidad](#seguridad-y-privacidad)
* [Casos de Uso](#casos-de-uso)
* [Mejores Prácticas](#mejores-practicas)
* [Solución de Problemas](#solucion-de-problemas)

***

## 🎯 Características Principales

### 💎 Plan Premium (Exclusivo)

⚠️ **El plugin de Donaciones es exclusivo del Plan Premium**

* ✅ **Panel de donaciones** personalizable con botones
* ✅ **Múltiples plataformas** integradas
* ✅ **Conversión automática** de dinero real a coins
* ✅ **Tickets de donación** privados para cada donante
* ✅ **Webhooks seguros** para procesamiento automático
* ✅ **Sistema de idempotencia** (sin duplicados)
* ✅ **Logging completo** de todas las donaciones

***

## 🌐 Plataformas Soportadas

### 💳 Stripe

**Recomendado para:**

* Pagos con tarjeta de crédito/débito
* Suscripciones recurrentes
* Pagos internacionales

**Ventajas:**

* ✅ Procesamiento instantáneo
* ✅ Webhooks automáticos (100% automático)
* ✅ Soporte mundial
* ✅ Muy seguro

**Desventajas:**

* ⚠️ Requiere cuenta de negocio
* ⚠️ Comisiones por transacción

***

### 💙 PayPal

**Recomendado para:**

* Donaciones rápidas
* Usuarios con cuenta PayPal
* Pagos desde móvil

**Ventajas:**

* ✅ Muy popular y confiable
* ✅ No requiere tarjeta
* ✅ App móvil integrada

**Desventajas:**

* ⚠️ Comisiones más altas
* ⚠️ Disponibilidad regional variable

***

### 💚 Mercado Pago

**Recomendado para:**

* Comunidades en Latinoamérica
* Pagos en moneda local
* Usuarios sin tarjeta internacional

**Ventajas:**

* ✅ Popular en LATAM
* ✅ Múltiples métodos de pago
* ✅ Monedas locales

**Desventajas:**

* ⚠️ Solo disponible en algunos países
* ⚠️ Configuración más compleja

***

### 🔗 Link Personalizado

**Recomendado para:**

* Otras plataformas de pago
* Transferencias bancarias
* Métodos personalizados

**Ventajas:**

* ✅ Cualquier plataforma de pago
* ✅ Sin comisiones del bot
* ✅ Control total

**Desventajas:**

* ⚠️ No hay automatización
* ⚠️ Verificación manual necesaria

***

## 👤 Configuración para Usuarios

### Vincular tu Usuario Discord

Para recibir automáticamente tus coins después de donar, es importante que tu ID de Discord esté vinculado correctamente:

**Métodos:**

1. **Abrir un ticket de donación primero** (recomendado)
   * El bot registra automáticamente tu ID
   * Luego procedes a donar
   * Las coins se acreditan automáticamente
2. **Incluir tu ID en los metadatos del pago**
   * En Stripe/PayPal: campo "Nota para el vendedor"
   * Escribe: `Discord ID: TU_ID_AQUI`
   * Ejemplo: `Discord ID: 123456789012345678`
3. **Contactar después de donar**
   * Si donaste sin vincular
   * Abre un ticket de soporte
   * Proporciona el comprobante
   * El administrador acreditará manualmente

***

## 💝 Cómo Donar

### Método 1: Usar el Panel de Donaciones

1. **Encuentra el panel en el servidor**
   * Generalmente en un canal #donaciones o #apoyo
2. **Haz clic en el botón 🎁 Donar**
   * Se crea un ticket privado para ti
3. **Selecciona tu plataforma preferida**
   * Aparece un menú con las opciones disponibles
   * Elige Stripe, PayPal, Mercado Pago o Link Personalizado
4. **Sigue las instrucciones**
   * Cada plataforma tiene su proceso
   * El bot te guía paso a paso
5. **Completa el pago**
   * Procesa en la plataforma externa
   * Vuelve a Discord
6. **Recibe tus coins**
   * **Automático** (Stripe/PayPal/MP): En segundos
   * **Manual** (Link): Espera verificación del staff

***

### Método 2: Donar Directamente

Si prefieres donar sin usar el bot:

1. **Ve directamente a la plataforma**
   * Usa los links publicados por el servidor
2. **Incluye tu Discord ID**
   * En el campo de notas/mensaje
   * Formato: `Discord ID: 123456789012345678`
3. **Completa el pago**
4. **Espera la acreditación**
   * Webhooks automáticos: 1-5 minutos
   * Verificación manual: Hasta 24 horas

***

## 🎁 Sistema de Recompensas

### Conversión Automática

El dinero que donas se convierte automáticamente a coins según los **exchange rates** configurados por el servidor.

**Ejemplo:**

```
Configuración del servidor:
- 1 USD = 100 coins
- 1 EUR = 110 coins
- 1 MXN = 5 coins

Tú donas: $20 USD
Recibes: 2,000 coins
```

### Notificación de Acreditación

Cuando tus coins son acreditadas:

1. **Mensaje directo (DM)**
   * Confirmación de la donación
   * Cantidad de coins recibidas
   * Nuevo balance total
   * Agradecimiento personalizado
2. **Actualización inmediata**
   * Puedes usar tus coins de inmediato
   * Ver tu balance con `/balance`
   * Comprar en la tienda

***

## 🎨 Panel de Donaciones

### Para Administradores

Crear el panel de donaciones:

```
/donation-panel [mensaje]
```

**Parámetros:**

* `mensaje` (opcional): Texto personalizado sobre el botón

**Ejemplo:**

```
/donation-panel mensaje:¡Apoya el servidor y recibe recompensas exclusivas!
```

**Resultado:**

* Se crea un mensaje con botón "🎁 Donar"
* Los usuarios pueden hacer clic para empezar el proceso
* Se crea un ticket privado por cada usuario

***

### Personalización

Desde el dashboard puedes configurar:

* **Mensaje de bienvenida** en el ticket
* **Plataformas activas** (cuáles mostrar)
* **Links de pago** para cada plataforma
* **Mensaje de agradecimiento** personalizado

***

## 💱 Exchange Rates

### ¿Qué son?

Los exchange rates determinan cuántas coins recibe un usuario por cada unidad de moneda real donada.

**Ejemplo de configuración:**

```
USD: 100 coins por dólar
EUR: 110 coins por euro
MXN: 5 coins por peso mexicano
ARS: 1 coin por peso argentino
BRL: 20 coins por real brasileño
```

### Consideraciones

**Para Administradores:**

1. **Valor justo**
   * Considera el poder adquisitivo de cada moneda
   * Mantén la proporción respecto a otras monedas
   * No subvalúes ni sobrevalores ninguna
2. **Simplicidad**
   * Usa números redondos cuando sea posible
   * Facilita el cálculo mental para los usuarios
   * Ejemplo: $1 = 100 coins (fácil de calcular)
3. **Actualización**
   * Revisa periódicamente las tasas de cambio reales
   * Ajusta si hay cambios drásticos en el mercado
   * Comunica los cambios a la comunidad

***

## ⚙️ Configuración

### En el Dashboard

Accede a <https://gubo.com.ar> > Tu Servidor > Donaciones

#### Configuración General

| Opción                        | Descripción                         | Predeterminado |
| ----------------------------- | ----------------------------------- | -------------- |
| **Plugin Habilitado**         | Activa el sistema de donaciones     | Desactivado    |
| **Mensaje de Ticket**         | Mensaje al abrir ticket de donación | Predeterminado |
| **Mensaje de Agradecimiento** | DM después de donar                 | Predeterminado |

#### Exchange Rates

Configura la tasa de conversión para cada moneda que aceptes:

| Moneda   | Ejemplo | Recomendación         |
| -------- | ------- | --------------------- |
| USD ($)  | 100     | Base común            |
| EUR (€)  | 110     | \~10% más que USD     |
| MXN ($)  | 5       | Según tipo de cambio  |
| ARS ($)  | 1       | Ajustar por inflación |
| BRL (R$) | 20      | Según tipo de cambio  |

#### Plataformas de Pago

**Stripe:**

* Client ID
* Webhook Secret
* Product IDs (opcionales)

**PayPal:**

* Hosted Button ID o
* Link de donación directo

**Mercado Pago:**

* Preference Base URL o
* Link de donación directo

**Link Personalizado:**

* URL de tu plataforma de pago preferida

***

## 🔒 Seguridad y Privacidad

### Para Usuarios

**¿Es seguro donar?**

* ✅ GUBO nunca maneja tu información de pago directamente
* ✅ Los pagos se procesan en las plataformas oficiales (Stripe/PayPal/etc.)
* ✅ Solo se comparte tu ID de Discord para acreditar coins

**¿Qué información se guarda?**

* Tu Discord ID
* Cantidad donada y moneda
* Fecha y hora de la donación
* Plataforma utilizada
* Cantidad de coins acreditadas

**¿Qué NO se guarda?**

* ❌ Números de tarjeta
* ❌ Contraseñas
* ❌ Información bancaria
* ❌ Dirección personal (a menos que la plataforma la requiera)

### Para Administradores

**Webhooks seguros:**

* Los webhooks están protegidos con secrets
* Se valida la autenticidad de cada notificación
* Previene fraude y duplicados

**Sistema de idempotencia:**

* Cada transacción tiene un ID único
* No se pueden procesar donaciones duplicadas
* Protege contra errores técnicos

***

## 💡 Casos de Uso

### 1. Servidor de Creadores de Contenido

**Configuración:**

* Plataformas: PayPal + Stripe
* Exchange: $1 USD = 100 coins
* Recompensas:
  * 500 coins: Rol Supporter (permanente)
  * 1000 coins: Rol VIP (30 días)
  * 2000 coins: Nombre destacado (permanente)

**Mensaje del panel:**

```
¡Apoya el canal y el servidor!
Cada donación te da coins para comprar roles exclusivos.
¡Gracias por tu apoyo! ❤️
```

***

### 2. Servidor de Gaming Competitivo

**Configuración:**

* Plataformas: Stripe + Mercado Pago
* Exchange: $1 USD = 50 coins
* Recompensas:
  * 250 coins: Acceso a scrims privados (7 días)
  * 500 coins: Coaching prioritario (14 días)
  * 1000 coins: Rol Pro Player (30 días)

**Mensaje del panel:**

```
¿Quieres mejorar y acceder a contenido exclusivo?
Dona y obtén coins para desbloquear beneficios de entrenamiento.
```

***

### 3. Servidor de Comunidad General

**Configuración:**

* Plataformas: PayPal + Link Personalizado
* Exchange: $1 USD = 200 coins
* Recompensas:
  * 1000 coins: Rol de Color (30 días)
  * 2000 coins: Rol Destacado (permanente)
  * 5000 coins: Canal de voz privado (permanente)

**Mensaje del panel:**

```
¡Ayuda a mantener el servidor activo!
Tus donaciones permiten mejoras constantes.
Recibe coins y personaliza tu experiencia.
```

***

## ✅ Mejores Prácticas

### Para Administradores

1. **Transparencia**
   * Explica claramente cómo se usan las donaciones
   * Publica los exchange rates
   * Comunica cambios con anticipación
2. **Configuración de plataformas**
   * Usa plataformas populares en tu región
   * Ofrece al menos 2 opciones
   * Mantén los links actualizados
3. **Recompensas justas**
   * Balancea el valor de las coins
   * No hagas las recompensas inalcanzables
   * Ofrece opciones para todos los presupuestos
4. **Seguridad**
   * Nunca pidas información de pago por Discord
   * Verifica que los webhooks estén configurados correctamente
   * Monitorea las transacciones regularmente
5. **Agradecimiento**
   * Personaliza mensajes de agradecimiento
   * Reconoce públicamente a los donadores (con su permiso)
   * Crea roles especiales para supporters

### Para Usuarios

1. **Verifica antes de donar**
   * Asegúrate de que sea el servidor oficial
   * Revisa los exchange rates
   * Lee qué recibirás por tu donación
2. **Guarda comprobantes**
   * Captura de pantalla de la transacción
   * Email de confirmación
   * ID de la transacción
3. **Paciencia con acreditación manual**
   * Algunos métodos requieren verificación
   * Puede tomar hasta 24 horas
   * Contacta a soporte si pasa más tiempo
4. **Dona responsablemente**
   * Solo dona lo que puedas permitirte
   * Las donaciones son voluntarias
   * No es necesario donar para disfrutar del servidor

***

## 🛠️ Solución de Problemas

### ❌ No recibí mis coins después de donar

**Soluciones:**

1. **Espera el tiempo de procesamiento**
   * Stripe/PayPal webhook: 1-5 minutos
   * Mercado Pago: 5-15 minutos
   * Link personalizado: Hasta 24 horas (verificación manual)
2. **Verifica tu ID de Discord**
   * ✅ ¿Incluiste tu ID en el pago?
   * ✅ ¿Está escrito correctamente?
   * ✅ ¿Es tu ID correcto? (Clic derecho en tu perfil > Copiar ID)
3. **Revisa tus mensajes directos**
   * Es posible que tengas los DMs bloqueados del servidor
   * Las coins se acreditan de todas formas
   * Verifica tu balance con el comando `/balance`
4. **Contacta al soporte**
   * Abre un ticket de soporte
   * Proporciona la siguiente información:
     * Comprobante de pago (captura de pantalla)
     * Tu Discord ID
     * Plataforma que utilizaste
     * Fecha y hora aproximada de la donación

***

### ❌ El panel de donaciones no funciona

**Soluciones:**

1. **Plugin deshabilitado**
   * ✅ Verifica que el plugin esté activo en el Dashboard
   * ✅ Asegúrate de haber guardado los cambios
2. **Sin plataformas configuradas**
   * ✅ Configura al menos una plataforma de pago en el Dashboard
   * ✅ Verifica que los links estén correctos
3. **Permisos del bot**
   * ✅ El bot necesita permiso de "Gestionar Canales" para crear tickets
   * ✅ El bot necesita permiso de "Enviar Mensajes"
   * ✅ Contacta a un administrador para verificar los permisos

***

### ❌ No puedo abrir un ticket de donación

**Soluciones:**

1. **Límite de tickets alcanzado**
   * ℹ️ Ya tienes un ticket de donación abierto
   * ✅ Cierra los tickets anteriores antes de abrir uno nuevo
2. **Plugin de tickets desactivado**
   * ✅ Verifica que ambos plugins estén activos: Donations y Tickets
   * ✅ Contacta a un administrador si el problema persiste

***

### ❌ Exchange rate incorrecto

**Soluciones:**

1. **Revisar configuración actualizada**
   * Los administradores pueden haber actualizado las tasas recientemente
   * Verifica los exchange rates actuales publicados en el servidor
2. **Conversión de moneda automática**
   * Algunas plataformas convierten automáticamente entre monedas
   * Ejemplo: Donaste en EUR pero se procesó en USD
   * Se usa la tasa de conversión de la moneda que el servidor recibió

***

## 📊 Comparativa Plan Free vs Premium

| Característica                | Free | Premium 💎 |
| ----------------------------- | ---- | ---------- |
| Panel de donaciones           | ❌    | ✅          |
| Tickets de donación           | ❌    | ✅          |
| Integración Stripe            | ❌    | ✅          |
| Integración PayPal            | ❌    | ✅          |
| Integración Mercado Pago      | ❌    | ✅          |
| Link personalizado            | ❌    | ✅          |
| Conversión automática a coins | ❌    | ✅          |
| Exchange rates configurables  | ❌    | ✅          |
| Webhooks automáticos          | ❌    | ✅          |
| Logging de transacciones      | ❌    | ✅          |
| Sistema de idempotencia       | ❌    | ✅          |

***

## 📞 Soporte

Si tienes problemas con el plugin de Donaciones:

1. ✅ Revisa esta guía completa
2. ✅ Consulta la sección de [Solución de Problemas](#solucion-de-problemas)
3. ✅ Verifica la configuración en el Dashboard
4. ✅ Confirma que tienes el Plan Premium activo
5. ✅ Contacta al soporte técnico de GUBO

***

**Última actualización:** Enero 2026

**Versión de la guía:** 1.0.0

***