Vender suscripciones VPN por USDT con un bot de Telegram: configuración paso a paso

Muchos servicios VPN venden por Telegram: el cliente ya está en el chat, así que la compra también debería hacerse ahí. Esta guía muestra cómo poner en marcha un bot listo en tu servidor: el cliente elige un plan, paga en USDT en TRC20, ERC20 o BEP20 o con otra moneda, y el bot crea o extiende el usuario en tu panel Marzban, 3x-ui o Remnawave y envía el enlace de suscripción al mismo chat. No necesitas monedero ni nodo de blockchain: el dinero llega a tu saldo de comercio en SnapEX Pay.

Cómo va una venta

cliente → /start → pulsa un plan
bot → SnapEX Pay: factura → botón «Pay»
cliente → paga en la página SnapEX Pay
SnapEX Pay → webhook firmado → bot
bot → factura desde la API → ¿paid?
bot → panel: crear o extender usuario
bot → cliente: enlace de suscripción

1. /start muestra tus planes como botones. Cada pulsación crea una factura de SnapEX Pay y el bot responde con un botón Pay («Pagar»).
2. El cliente elige una moneda en la página de pago y paga. Cuando la factura está pagada, SnapEX Pay envía un webhook firmado al bot.
3. El bot comprueba la firma, pide la factura a la API de SnapEX Pay y activa el usuario solo si allí el estado es paid y la factura corresponde a un pedido que creó el propio bot.

El nombre de usuario en el panel es tg<telegram_id>, así que cada cuenta de Telegram corresponde exactamente a un usuario de VPN.

Qué necesitas

• Un token de bot de @BotFather.
• Acceso de administrador a un panel Marzban, 3x-ui (MHSanaei) o Remnawave (2.x o 3.x). Sin panel, el bot solo puede cobrar (PANEL_TYPE=none) y el acceso lo entregas tú.
• Un servidor con Docker Compose (o Python 3.12).
• Una dirección pública HTTPS para el webhook: SnapEX Pay solo entrega webhooks a direcciones https://.
• Una cuenta de comercio en SnapEX Pay: regístrate en pay.snapex.pro.

El bot usa long polling, así que Telegram no necesita un puerto abierto en tu servidor: solo tiene que ser accesible el puerto del webhook detrás de HTTPS.

Paso 1. Descarga el bot

Descarga el archivo snapexpay-telegram-vpn-bot-1.1.0.zip (MIT, gratis) y crea el archivo de configuración:

curl -fsSLO https://pay.snapex.pro/downloads/telegram-vpn-bot/snapexpay-telegram-vpn-bot-1.1.0.zip
unzip snapexpay-telegram-vpn-bot-1.1.0.zip
cd snapexpay-telegram-vpn-bot-1.1.0
cp .env.example .env

Toda la configuración está en .env. Pon el token del bot en TELEGRAM_BOT_TOKEN y el nombre de tu tienda en SHOP_NAME: se muestra en el mensaje de /start y en la descripción de la factura.

Paso 2. Obtén una clave API

En el panel de comercio de SnapEX Pay abre Developers y emite una clave API. Se muestra una sola vez: cópiala enseguida en SNAPEX_API_KEY. Una clave emitida en el panel recibe todos los permisos de la Merchant API, incluidos invoices.read e invoices.write, que el bot necesita. Reemitir la clave revoca la anterior al instante, así que actualiza .env al mismo tiempo.

Dos ajustes más del pago:

• SNAPEX_FEE_ON: merchant (por defecto), el cliente paga exactamente el precio del plan y las comisiones se descuentan de lo que recibes tú; customer, las comisiones se suman encima. Más: Quién paga la comisión de una factura cripto.
• SNAPEX_EXPIRES_MINUTES: cuánto tiempo se puede pagar la factura, 60 minutos por defecto (de 1 a 1440).

Paso 3. Describe tus planes

Los planes van en una línea en PLANS: id:days:price_usd:traffic_bytes, separados por comas. 0 bytes significa tráfico ilimitado.

PLANS=week:7:2.00:0,month:30:5.00:0,quarter:90:12.00:107374182400

Aquí quarter son 90 días con 100 GiB de tráfico. El id se muestra en el botón ("month — $5.00 / 30d"), así que mantenlo corto: letras latinas, dígitos, _ y -. Los precios están en USD; la factura mínima es de 0.50 USD.

Cada pedido guarda una copia de su plan, así que puedes cambiar los precios más adelante sin afectar a los pedidos ya pagados.

Paso 4. Conecta el panel

Indica PANEL_TYPE y los datos de acceso a tu panel.

Marzban: PANEL_TYPE=marzban:

• MARZBAN_URL, MARZBAN_USERNAME, MARZBAN_PASSWORD: la dirección del panel y un usuario administrador (o un token de administrador ya generado en MARZBAN_TOKEN).
• MARZBAN_SUB_URL: solo si Marzban devuelve enlaces relativos /sub/<token> (XRAY_SUBSCRIPTION_URL_PREFIX vacío): la base pública del enlace.

3x-ui: PANEL_TYPE=3xui:

• XUI_URL: la dirección del panel incluida la ruta base web, si la configuraste (https://xui.example.com:2053/secretpath).
• XUI_USERNAME, XUI_PASSWORD: la autenticación de dos factores debe estar desactivada para esta cuenta.
• XUI_INBOUND_ID: el inbound al que se añaden los clientes nuevos (vless, vmess, trojan o shadowsocks).
• XUI_SUB_URL: la base de la suscripción, por ejemplo https://xui.example.com:2096/sub. Sin ella el bot envía solo el subId.

Remnawave: PANEL_TYPE=remnawave:

• REMNAWAVE_URL y REMNAWAVE_TOKEN: la dirección del panel y un token API de API Tokens.
• REMNAWAVE_SQUAD_UUIDS: los squads internos para los usuarios nuevos, separados por comas. Sin squad, un usuario nuevo no tiene servidores.

Paso 5. Arranca el bot detrás de HTTPS

docker compose up -d --build
docker compose logs -f bot

El bot escucha en el puerto 8080: /webhook para SnapEX Pay y /health para comprobaciones. Ponlo detrás de un proxy inverso con TLS, por ejemplo Caddy:

pay-bot.example.com {
    reverse_proxy 127.0.0.1:8080
}

El proxy debe pasar el cuerpo de la petición sin cambios: la firma se calcula sobre el cuerpo crudo.

Paso 6. Configura el webhook

En el panel de comercio, en la página Developers, introduce la URL del webhook https://pay-bot.example.com/webhook y guarda. El secreto de firma whsec_… se muestra una sola vez, justo después de guardar por primera vez: cópialo en SNAPEX_WEBHOOK_SECRET y reinicia el bot: docker compose up -d.

El panel de comercio tiene una URL de webhook por cuenta y a ella llegan todos los eventos. El bot actúa solo con los eventos de facturas y confirma la recepción del resto.

Cómo comprueba el bot una notificación:

• la cabecera Webhook-Signature: HMAC-SHA256 de {Webhook-Timestamp}.{cuerpo crudo de la petición} con tu secreto; las peticiones sin firma o alteradas reciben 401;
• Webhook-Timestamp dentro de 5 minutos respecto al reloj del servidor: mantén NTP activo;
• la propia factura, leída de nuevo en la API de SnapEX Pay con tu clave: el usuario se activa solo si allí el estado es paid.

Si en ese momento el panel o la API de SnapEX Pay no están disponibles, el bot responde 502 y SnapEX Pay reintenta la entrega (hasta 5 intentos). Las entregas repetidas o simultáneas activan una factura una sola vez. Más sobre firmas y reintentos: Webhooks de pagos cripto.

Paso 7. Una compra de prueba sin dinero real

1. Pon SNAPEX_ENVIRONMENT=test y reinicia: docker compose up -d.
2. Envía /start a tu bot desde tu propia cuenta de Telegram y pulsa un plan.
3. Pulsa Pay. La página de SnapEX Pay muestra la etiqueta Test. Elige cualquier moneda y red: la página muestra una dirección de prueba y unos 10 segundos después el pago se confirma solo. No hay que enviar nada.
4. El bot debería enviar "Payment received" («Pago recibido») y el enlace de suscripción, y en el panel debería aparecer el usuario tg<tu telegram id>. Si no, revisa docker compose logs -f bot y el registro de entregas en la página Developers.
5. Pon SNAPEX_ENVIRONMENT=live y reinicia.

Mientras el bot está en test, cualquier plan comprado con él se activa sin dinero, así que haz la prueba rápido. Más: Cómo probar pagos cripto sin dinero real.

Qué ve el cliente

• /start: el nombre de tu tienda, una línea sobre el pago con USDT (TRC20 / ERC20 / BEP20) u otras monedas y los botones de los planes.
• Tras pulsar uno: el plan, sus días, el precio y el número de factura, además de un botón "Pay $5.00 with crypto" («Pagar $5.00 con cripto»).
• La página de SnapEX Pay con la elección de moneda: USDT en TRC20, ERC20 y BEP20 y otras monedas (más de 50 en total) cuando SnapEX Pay las ofrece para el importe de la factura.
• Después del pago: "Payment received" y el enlace de suscripción en el mismo chat. Con PANEL_TYPE=none el mensaje dice que el administrador enviará el acceso en breve.

Los mensajes del propio bot están en inglés; solo el nombre de la tienda y los nombres de los planes son tuyos.

Un cliente que vuelve paga desde la misma cuenta de Telegram y su usuario se extiende desde el vencimiento actual (o desde ahora, si ya pasó); un plan con límite de tráfico empieza con una cuota nueva. Detalles: Renovación de suscripciones VPN pagadas con cripto.

Si el cliente envía menos del total, el usuario no se activa: el bot da acceso solo con una factura paid. Lo recibido llega a tu saldo de SnapEX Pay y el resto lo resuelves con el cliente. Cómo funcionan los pagos incompletos: El cliente envió menos que la factura.

Si algo no funciona

• "Payment is unavailable right now" («El pago no está disponible ahora») tras pulsar un plan. El bot no pudo crear la factura: revisa SNAPEX_API_KEY (clave incorrecta o revocada) y los logs.
• El webhook recibe 401 "bad webhook signature". SNAPEX_WEBHOOK_SECRET no coincide o el proxy modifica el cuerpo de la petición. Comprueba también que el reloj del servidor esté sincronizado.
• El cliente pagó y no recibió nada. Busca provision failed en los logs. SnapEX Pay sigue reintentando la entrega; cuando el panel vuelva a funcionar, la siguiente entrega activa el usuario, o puedes repetir la entrega desde el registro en el panel de comercio.
• Marzban envía un enlace sin host. Configura XRAY_SUBSCRIPTION_URL_PREFIX en Marzban o MARZBAN_SUB_URL en el bot.
• 3x-ui: "login failed". Revisa XUI_URL (con la ruta base web) y el usuario, y desactiva la autenticación de dos factores para esa cuenta.
• Remnawave: el usuario se crea, pero la suscripción está vacía. Pon en REMNAWAVE_SQUAD_UUIDS los squads con tus nodos.
• Varias copias del bot. Ejecuta una sola instancia por DATA_DIR: la protección contra duplicados funciona dentro de un proceso y su archivo SQLite.

Cuánto cuesta

1% por pago, sin cuota de alta ni cuota mensual. El bot es gratis.

Página del bot: Bot de Telegram para VPN. ¿Vendes desde la tienda del propio panel? Mira Pagos cripto en Xboard y V2Board. Panorama para servicios VPN: Pagos cripto para servicios VPN. Registro: pay.snapex.pro.