Pagos cripto para Marzban VPN
Un pequeño servicio autoalojado que vende suscripciones VPN de Marzban por cripto a través de SnapEX Pay. Tu tienda o bot de Telegram le pide un enlace de pago, el cliente paga en la página de SnapEX Pay (USDT en TRC20, ERC20 o BEP20, además de otros métodos que SnapEX ofrezca para ese importe), y una vez pagada la factura el servicio crea o renueva el usuario en tu panel Marzban y devuelve el enlace de suscripción.
Gratis. Versión 1.1.0.
Qué hace
- Sin billetera ni nodo de blockchain que mantener.
POST /v1/checkoutcrea una factura de SnapEX Pay para un plan y devuelvepay_url;GET /v1/orders/{invoice_id}devuelve el estado y la URL de suscripción de los registros del propio servicio (los actualiza el webhook), para que un bot pueda consultarlo periódicamente.- Webhook firmado (HMAC-SHA256, ventana de 5 minutos para la marca de tiempo). Nunca se confía en el cuerpo del webhook: la factura se vuelve a leer desde la API de SnapEX Pay y el usuario se da de alta solo cuando está pagada.
- Idempotente: las entregas repetidas o simultáneas del webhook dan de alta una factura solo una vez.
- Los usuarios nuevos reciben todos los protocolos que tienen un inbound en tu panel; los existentes se renuevan desde su vencimiento actual (o desde ahora si ya pasó o el usuario no tenía vencimiento), y en los planes con tráfico la cuota del plan se suma al límite actual o al tráfico consumido, el que sea mayor.
- Los planes se definen con una sola variable de entorno; los pedidos se guardan en SQLite. El modo de prueba no mueve fondos reales.
Instalación
- Descarga y descomprime el archivo, y en su carpeta ejecuta
cp .env.example .env. - En el panel del comercio de SnapEX Pay crea una clave API con los permisos
invoices.readeinvoices.writey ponla enSNAPEX_API_KEY. - Define
API_TOKEN(por ejemploopenssl rand -hex 32),MARZBAN_URLy las credenciales de administrador de Marzban (MARZBAN_USERNAMEyMARZBAN_PASSWORD), y tus planes enPLANS(id:days:usd:traffic_bytes,0bytes = ilimitado). - Arráncalo:
docker compose up -d, y luego compruebacurl http://127.0.0.1:8080/health. Pon el servicio detrás de un proxy inverso HTTPS. - En el panel → Developers configura la URL del webhook como
https://<your service>/webhook, copia el secreto de firmawhsec_…(se muestra una sola vez, al guardar la URL por primera vez) enSNAPEX_WEBHOOK_SECRETy reinicia el servicio. - Desde tu tienda o bot llama a
POST /v1/checkoutconAuthorization: Bearer <API_TOKEN>, envíapay_urlal cliente y consultaGET /v1/orders/{invoice_id}para obtener el enlace de suscripción. Para una prueba sin fondos reales, defineSNAPEX_ENVIRONMENT=test.
Ajustes
| SNAPEX_API_KEY | Clave API de comercio (smk_…) con invoices.read e invoices.write. |
|---|---|
| SNAPEX_WEBHOOK_SECRET | Secreto de firma (whsec_…) de tu endpoint de webhook. |
| SNAPEX_ENVIRONMENT | live o test. Las facturas de prueba no mueven fondos reales. |
| SNAPEX_FEE_ON | Quién paga la comisión del servicio SnapEX: merchant o customer. |
| API_TOKEN | Token Bearer que tu bot o tienda envía a /v1/checkout y /v1/orders/*. |
| MARZBAN_URL, MARZBAN_USERNAME, MARZBAN_PASSWORD | URL del panel y credenciales de administrador (o un MARZBAN_TOKEN ya generado; los tokens caducan, así que para un servicio de larga duración es mejor usuario y contraseña). |
| PLANS | id:days:usd:traffic_bytes separados por comas, por defecto month:30:5.00:0,quarter:90:12.00:0. |
| SNAPEX_PARTNER_ID | Opcional: el Partner ID del integrador que configuró el módulo (programa de referidos de SnapEX Pay). Déjalo vacío si lo instalas tú mismo. |
Preguntas
¿Puedo usarlo desde un bot de Telegram?
Sí. El bot llama a POST /v1/checkout, envía pay_url al usuario y consulta GET /v1/orders/{invoice_id} para obtener el enlace de suscripción. También hay un bot de Telegram completo para Marzban, 3x-ui y Remnawave.
¿Qué pasa con un usuario existente que vuelve a pagar?
La suscripción se renueva desde el vencimiento actual (o desde ahora si ya pasó o el usuario no tenía vencimiento); en los planes con tráfico la cuota del plan se suma al límite actual o al tráfico consumido, el que sea mayor.
¿Puede un webhook dar de alta a un usuario dos veces?
No. Las entregas repetidas o simultáneas dan de alta una factura solo una vez, y el servicio vuelve a leer la factura desde la API de SnapEX Pay antes de hacer nada.
¿Y si el panel Marzban está caído cuando llega el pago?
El manejador del webhook devuelve 502, y SnapEX Pay reintenta la entrega más tarde.
¿Por qué necesito HTTPS?
SnapEX Pay entrega webhooks solo a URL https://, así que pon el servicio detrás de nginx, Caddy o Traefik.
Otras integraciones
¿Listo para aceptar cripto?
Crea una cuenta de comercio, obtén una clave API y conecta el módulo. 1% por pago, sin cuota mensual.