Como vender assinaturas de VPN por USDT com um bot do Telegram: configuração passo a passo

Muitos serviços de VPN vendem pelo Telegram: o cliente já está no chat, então a compra também deve acontecer ali. Este guia mostra como colocar no ar um bot pronto no seu servidor. O cliente escolhe um plano e paga em USDT nas redes TRC20, ERC20 ou BEP20 ou em outra moeda. O bot cria ou renova o usuário no seu painel Marzban, 3x-ui ou Remnawave e envia o link da assinatura no mesmo chat. Você não precisa manter carteira nem node de blockchain: o dinheiro cai no seu saldo de comerciante na SnapEX Pay.

Como funciona uma venda

cliente → /start → toca em um plano
bot → SnapEX Pay: fatura → botão “Pay”
cliente → paga na página da SnapEX Pay
SnapEX Pay → webhook assinado → bot
bot → GET da fatura na API → paid?
bot → painel: cria ou renova o usuário
bot → cliente: link da assinatura

1. O /start mostra seus planos como botões. Cada toque cria uma fatura na SnapEX Pay, e o bot responde com o botão Pay (“Pagar”).
2. O cliente escolhe uma moeda na página de pagamento e paga. Quando a fatura é paga, a SnapEX Pay envia um webhook assinado ao bot.
3. O bot verifica a assinatura HMAC, consulta a fatura na API da SnapEX Pay e só libera o usuário se o status ali for paid e se a fatura pertencer a um pedido criado pelo próprio bot.

O nome de usuário no painel é tg<telegram_id>. Assim, cada conta do Telegram corresponde a exatamente um usuário da VPN.

O que você precisa

• Um token de bot do @BotFather.
• Acesso de administrador a um painel Marzban, 3x-ui (MHSanaei) ou Remnawave (2.x ou 3.x). Sem painel, o bot só recebe pagamentos (PANEL_TYPE=none), e você mesmo entrega o acesso.
• Um servidor com Docker Compose (ou Python 3.12).
• Um endereço público com HTTPS para o webhook: a SnapEX Pay só entrega webhooks para URLs https://.
• Uma conta de comerciante na SnapEX Pay: crie a sua em pay.snapex.pro.

O bot usa long polling, então o Telegram não precisa de nenhuma porta aberta no seu servidor. Só a porta do webhook, atrás do HTTPS, precisa estar acessível.

Passo 1. Baixe o bot

Baixe o arquivo snapexpay-telegram-vpn-bot-1.1.0.zip (MIT, gratuito) e crie o arquivo de configurações:

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

Todas as configurações ficam no .env. Coloque o token do bot em TELEGRAM_BOT_TOKEN e o nome da sua loja em SHOP_NAME. Ele aparece na mensagem do /start e na descrição da fatura.

Passo 2. Gere uma chave de API

No painel do comerciante da SnapEX Pay, abra Desenvolvedores e gere uma chave de API. Ela aparece uma única vez: copie-a na hora para SNAPEX_API_KEY. A chave gerada no painel recebe todas as permissões da API do comerciante, inclusive invoices.read e invoices.write, de que o bot precisa. Gerar uma nova chave revoga a antiga imediatamente, então atualize o .env ao mesmo tempo.

Mais duas configurações de pagamento:

• SNAPEX_FEE_ON: com merchant (padrão), o cliente paga exatamente o preço do plano, e as taxas saem do valor que você recebe; com customer, as taxas são somadas ao preço. Saiba mais: Quem paga as taxas de uma fatura em cripto.
• SNAPEX_EXPIRES_MINUTES: por quanto tempo a fatura pode ser paga. O padrão é 60 minutos (de 1 a 1440).

Passo 3. Defina seus planos

Os planos ficam em uma única linha em PLANS, no formato id:days:price_usd:traffic_bytes, separados por vírgulas. 0 bytes significa tráfego ilimitado.

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

Aqui, quarter são 90 dias com 100 GiB de tráfego. O id aparece no botão (“month — $5.00 / 30d”), então mantenha-o curto: letras latinas, dígitos, _ e -. Os preços são em USD, e a fatura mínima é de US$ 0,50.

Cada pedido guarda uma cópia do seu plano. Por isso, você pode mudar os preços depois sem afetar os pedidos já pagos.

Passo 4. Conecte o painel

Defina PANEL_TYPE e os dados de acesso ao seu painel.

Marzban: PANEL_TYPE=marzban:

• MARZBAN_URL, MARZBAN_USERNAME, MARZBAN_PASSWORD: o endereço do painel e um login de administrador (ou um token de administrador pronto em MARZBAN_TOKEN).
• MARZBAN_SUB_URL: só se o Marzban devolver links relativos /sub/<token> (XRAY_SUBSCRIPTION_URL_PREFIX vazio). É a base pública do link.

3x-ui: PANEL_TYPE=3xui:

• XUI_URL: o endereço do painel, incluindo o caminho base da web, se você tiver definido um (https://xui.example.com:2053/secretpath).
• XUI_USERNAME, XUI_PASSWORD: a autenticação de dois fatores precisa estar desativada nessa conta.
• XUI_INBOUND_ID: o inbound em que os novos clientes são adicionados (vless, vmess, trojan ou shadowsocks).
• XUI_SUB_URL: a base da assinatura, por exemplo https://xui.example.com:2096/sub. Sem ela, o bot envia só o subId.

Remnawave: PANEL_TYPE=remnawave:

• REMNAWAVE_URL e REMNAWAVE_TOKEN: o endereço do painel e um token de API criado em API Tokens.
• REMNAWAVE_SQUAD_UUIDS: os squads internos para novos usuários, separados por vírgulas. Sem squad, o novo usuário fica sem servidores.

Passo 5. Inicie o bot atrás do HTTPS

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

O bot escuta na porta 8080: /webhook para a SnapEX Pay e /health para verificações. Coloque-o atrás de um proxy reverso com TLS, por exemplo o Caddy:

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

O proxy precisa repassar o corpo da requisição sem alterações, porque a assinatura HMAC é calculada sobre o corpo bruto.

Passo 6. Configure o webhook

No painel, na página Desenvolvedores, informe a URL do webhook https://pay-bot.example.com/webhook e salve. A chave secreta de assinatura whsec_… aparece uma única vez, logo depois do primeiro salvamento. Copie-a para SNAPEX_WEBHOOK_SECRET e reinicie o bot: docker compose up -d.

O painel tem uma URL de webhook por conta, e todos os eventos vão para ela. O bot só age nos eventos de fatura e confirma o recebimento dos demais.

Como o bot verifica uma notificação:

• o header Webhook-Signature: HMAC-SHA256 de {Webhook-Timestamp}.{corpo bruto da requisição} com a sua chave secreta; requisições sem assinatura ou adulteradas recebem 401;
• o Webhook-Timestamp precisa estar a no máximo 5 minutos do relógio do servidor, então mantenha o NTP ativo;
• a própria fatura, lida de novo na API da SnapEX Pay com a sua chave: o usuário só é liberado se o status ali for paid.

Se o painel ou a API da SnapEX Pay estiver fora do ar nesse momento, o bot responde 502, e a SnapEX Pay tenta entregar de novo (até 5 tentativas). Entregas repetidas ou simultâneas liberam uma fatura uma única vez. Mais sobre assinaturas HMAC e novas tentativas: Webhooks de pagamentos em cripto.

Passo 7. Uma compra de teste sem dinheiro real

1. Defina SNAPEX_ENVIRONMENT=test e reinicie: docker compose up -d.
2. Envie /start para o seu bot pela sua própria conta do Telegram e toque em um plano.
3. Toque em Pay. A página da SnapEX Pay mostra o selo Teste. Escolha qualquer moeda e rede: a página mostra um endereço de teste e, cerca de 10 segundos depois, o pagamento se confirma sozinho. Não é preciso enviar nada.
4. O bot deve enviar “Payment received” (“Pagamento recebido”) e o link da assinatura, e o usuário tg<seu telegram id> deve aparecer no painel. Se isso não acontecer, veja docker compose logs -f bot e o bloco “Entregas do webhook” na página Desenvolvedores.
5. Defina SNAPEX_ENVIRONMENT=live e reinicie.

Enquanto o bot estiver em test, todo plano comprado por ele é liberado sem pagamento. Por isso, faça um teste curto. Saiba mais: Como testar pagamentos em cripto sem dinheiro real.

O que o cliente vê

• /start: o nome da sua loja, uma linha sobre o pagamento em USDT (TRC20 / ERC20 / BEP20) ou em outras moedas e os botões dos planos.
• Depois do toque: o plano, a quantidade de dias, o preço e o número da fatura, além do botão “Pay $5.00 with crypto” (“Pagar US$ 5,00 em cripto”).
• A página da SnapEX Pay com a escolha de moedas: USDT nas redes TRC20, ERC20 e BEP20 e outras moedas (mais de 50 no total), quando a SnapEX Pay as oferece para o valor da fatura.
• Depois do pagamento: “Payment received” e o link da assinatura no mesmo chat. Com PANEL_TYPE=none, a mensagem avisa que o administrador vai enviar o acesso em breve.

As mensagens do próprio bot são em inglês. Só o nome da loja e os nomes dos planos são seus.

O cliente que volta paga pela mesma conta do Telegram, e o usuário dele é renovado a partir do vencimento atual (ou a partir de agora, se o prazo já passou). Um plano com limite de tráfego começa com uma cota nova. Detalhes: Renovação de assinaturas de VPN pagas em cripto.

Se o cliente enviar menos que o total, o usuário não é liberado: o bot só dá acesso com uma fatura paid. O valor recebido entra no seu saldo na SnapEX Pay, e você acerta o restante com o cliente. Como funcionam os pagamentos parciais: O cliente enviou menos do que o valor da fatura.

Se algo não funcionar

• “Payment is unavailable right now” (“O pagamento não está disponível no momento”) depois de tocar em um plano. O bot não conseguiu criar a fatura: confira a SNAPEX_API_KEY (chave errada ou revogada) e os logs.
• O webhook recebe 401 “bad webhook signature”. A SNAPEX_WEBHOOK_SECRET não confere, ou o proxy altera o corpo da requisição. Confira também se o relógio do servidor está sincronizado.
• O cliente pagou e não recebeu nada. Procure provision failed nos logs. A SnapEX Pay continua tentando entregar. Quando o painel voltar a funcionar, a próxima entrega libera o usuário. Você também pode reenviar a entrega pelo bloco “Entregas do webhook” no painel.
• O Marzban envia um link sem host. Defina XRAY_SUBSCRIPTION_URL_PREFIX no Marzban ou MARZBAN_SUB_URL no bot.
• 3x-ui: “login failed”. Confira a XUI_URL (com o caminho base da web) e o login, e desative a autenticação de dois fatores nessa conta.
• Remnawave: o usuário é criado, mas a assinatura vem vazia. Coloque em REMNAWAVE_SQUAD_UUIDS os squads que têm os seus nodes.
• Várias cópias do bot. Rode uma única instância por DATA_DIR: a proteção contra duplicidade funciona dentro de um processo e do arquivo SQLite dele.

Quanto custa

Taxa de 1% por pagamento, sem taxa de adesão e sem mensalidade. O bot é gratuito.

Página do bot: Bot de VPN no Telegram. Prefere vender pela loja do próprio painel? Veja Pagamentos em cripto no Xboard e no V2Board. Visão geral para serviços de VPN: Pagamentos em cripto para serviços de VPN. Cadastro: pay.snapex.pro.