Comunidades no Telegram com afiliados

Uma comunidade paga no Telegram pode receber em USDT ou USDC com a Aliquot e dar a cada afiliado que trouxe um membro uma porcentagem fixa do pagamento desse membro. O bot cria uma fatura que nomeia o afiliado em splits, abre o checkout hospedado como Mini-App do Telegram e envia um link de convite quando o webhook invoice.paid chega. A parte do afiliado é creditada no saldo dele no momento em que o pagamento é confirmado, e você faz o payout para a wallet dele com uma única chamada à API. Sem planilhas, sem acerto manual de comissões.

Este guia usa o Sandbox (BSC_TESTNET, USDT) e chamadas fetch diretas à Bot API do Telegram, então funciona com qualquer biblioteca de bots. Você precisa de uma API key da Aliquot (veja o Início rápido), de um token de bot do @BotFather e do bot adicionado como administrador do canal ou grupo privado, com permissão para convidar usuários.

Como o dinheiro é dividido

Para uma assinatura de 20.00 USD com 20 % para o afiliado e o fee_payer padrão, CUSTOMER:

Cada parte é uma porcentagem do preço base e é registrada no ledger de partidas dobradas quando a fatura é paga. Com fee_payer MERCHANT, o comprador envia exatamente 20.00 e a taxa sai da sua parte. A conta completa está em Ledger e splits.

1. Dê a cada afiliado uma conta de parceiro e um link

Um afiliado é uma conta PARTNER. Crie uma por afiliado (permissão crypto-accounts:create), com uma referência que você consiga derivar dos seus próprios dados, como o ID de usuário dele no Telegram:

curl -X POST https://api.aliquot.cc/api/v1/crypto/accounts \
  -H "Authorization: Bearer $ALIQUOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "PARTNER", "reference": "aff-5550001", "name": "Ana (afiliada)", "settlement_address": "0x7a3B9c1D5e2F4a6B8c0D1e3F5a7B9c2D4e6F8a0B" }'

As referências têm de 2 a 63 caracteres entre letras minúsculas, dígitos, _ e -, e são únicas na sua organização; uma duplicada responde 409, então você pode tratar esse caso como "já existe".

Dê ao afiliado um deep link do Telegram com a referência dele: https://t.me/<seu_bot>?start=aff-5550001. Quando alguém abre esse link, o Telegram envia ao seu bot a mensagem /start aff-5550001. Guarde essa referência junto ao ID de usuário do Telegram do novo membro no seu banco de dados: é quem recebe a parte quando esse membro pagar.

2. Crie a fatura com o split do afiliado

Quando o membro pedir para entrar, crie uma fatura. Coloque o ID de usuário dele no Telegram em merchant_order_id: os webhooks da fatura o devolvem, assim você sabe quem convidar.

const BOT = `https://api.telegram.org/bot${process.env.TELEGRAM_BOT_TOKEN}`;

async function createMembershipInvoice(telegramUserId, affiliateRef) {
  const orderId = `tg-${telegramUserId}-${Date.now()}`;
  const res = await fetch('https://api.aliquot.cc/api/v1/crypto/invoices', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ALIQUOT_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': orderId,
    },
    body: JSON.stringify({
      amount: '20.00',
      title: 'Canal VIP · 30 dias',
      network: 'BSC_TESTNET',
      token: 'USDT',
      merchant_order_id: orderId,
      ...(affiliateRef ? { splits: [{ account: affiliateRef, percent: 20 }] } : {}),
    }),
  });
  const invoice = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${invoice.code}: ${invoice.message}`);
  return invoice; // invoice.pay_url é o checkout hospedado
}

• Sem afiliado, não envie splits: sua conta platform fica com todo o líquido.
• Uma referência de conta desconhecida em splits é um 422 nesse campo. Crie a conta de parceiro antes.
• No Live é a mesma requisição em BSC_MAINNET com uma key Live. Veja Redes e tokens para todos os pares.

3. Abra o checkout como Mini-App

Adicione ?tg=1 ao pay_url e envie como botão web_app. O Telegram abre o checkout hospedado dentro do chat: o mesmo valor, QR code, botão de wallet e status de confirmação ao vivo de /pay/:id, com a ação principal no MainButton do próprio Telegram.

async function sendCheckout(chatId, invoice) {
  await fetch(`${BOT}/sendMessage`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      chat_id: chatId,
      text: `Canal VIP · 30 dias: ${invoice.total} ${invoice.token}`,
      reply_markup: {
        inline_keyboard: [[{ text: 'Pagar com USDT', web_app: { url: `${invoice.pay_url}?tg=1` } }]],
      },
    }),
  });
}

O Telegram só permite botões web_app em um chat privado entre o usuário e o bot. Em um grupo, envie um botão url comum com o pay_url: ele abre o mesmo checkout no navegador.

4. Envie o convite quando invoice.paid chegar

Inscreva um endpoint em invoice.paid (Developers → Webhooks) e verifique a assinatura exatamente como no receptor do Início rápido. Depois leia o ID de usuário do Telegram a partir do merchant_order_id e crie um link de convite de uso único:

async function onInvoicePaid(event) {
  const [, telegramUserId] = event.data.merchant_order_id.split('-');
  const invite = await fetch(`${BOT}/createChatInviteLink`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      chat_id: process.env.VIP_CHAT_ID,
      member_limit: 1,
      expire_date: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
    }),
  }).then((r) => r.json());

  await fetch(`${BOT}/sendMessage`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ chat_id: telegramUserId, text: `Pagamento recebido. Seu convite: ${invite.result.invite_link}` }),
  });
}

Torne isso idempotente em event.data.invoice_id: uma entrega que o seu endpoint não responde com 2xx é reenviada, então o mesmo evento pode chegar mais de uma vez (veja Webhooks). invoice.paid também é disparado para faturas OVERPAID; a diferença paga a mais fica retida para o comprador resgatar (veja Reembolsos).

Entregue apenas a partir do webhook. Um pagamento conta quando atinge o limite de confirmações da sua rede; veja Confirmações.

5. Pague os afiliados

A parte de cada afiliado fica no saldo de parceiro dele. Consulte com GET /api/v1/crypto/balances e envie para a wallet dele com um payout:

curl -X POST https://api.aliquot.cc/api/v1/crypto/payouts \
  -H "Authorization: Bearer $ALIQUOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-11-aff-5550001" \
  -d '{
    "account": "aff-5550001",
    "network": "BSC_TESTNET",
    "token": "USDT",
    "amount": "40.00",
    "destination_address": "0x7a3B9c1D5e2F4a6B8c0D1e3F5a7B9c2D4e6F8a0B"
  }'

A key precisa de crypto-payouts:create, que só um usuário com autenticação de dois fatores pode conceder. Cada payout tem uma taxa que sai do amount e um máximo por payout; os dois estão em Payouts. Você também pode fazer o payout pelo dashboard (Payouts → New payout) com um código do seu app autenticador.

Próximos passos

• Ledger e splits: markup, vários parceiros em uma fatura e os lançamentos do ledger.
• Links de pagamento: uma página de preço fixo que você pode fixar em um canal, quando não precisa de atribuição por membro.
• Webhooks: todos os eventos, reenvios e rotação do segredo.