Comunidades de Telegram con afiliados

Una comunidad paga de Telegram puede cobrar en USDT o USDC con Aliquot y darle a cada afiliado que trajo un miembro un porcentaje fijo del pago de ese miembro. El bot crea una factura que nombra al afiliado en splits, abre el checkout hosteado como Mini-App de Telegram y manda un link de invitación cuando llega el webhook invoice.paid. La parte del afiliado se acredita en su propio saldo en el momento en que se confirma el pago, y se la pagás a su wallet con una sola llamada a la API. Sin planillas ni liquidaciones de comisiones a mano.

Esta guía usa Sandbox (BSC_TESTNET, USDT) y llamadas fetch directas a la Bot API de Telegram, así que sirve con cualquier librería de bots. Necesitás una API key de Aliquot (ver Inicio rápido), un token de bot de @BotFather y el bot agregado como administrador del canal o grupo privado, con permiso para invitar usuarios.

Cómo se divide la plata

Para una membresía de 20.00 USD con una parte de afiliado del 20 % y el fee_payer por defecto, CUSTOMER:

Cada parte es un porcentaje del precio base y se registra en el ledger de partida doble cuando se paga la factura. Con fee_payer MERCHANT el comprador envía exactamente 20.00 y la comisión sale de tu parte. La cuenta completa está en Ledger y splits.

1. Dale a cada afiliado una cuenta de socio y un link

Un afiliado es una cuenta PARTNER. Creá una por afiliado (permiso crypto-accounts:create), con una referencia que puedas derivar de tus propios datos, como su ID de usuario de 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" }'

Las referencias tienen de 2 a 63 caracteres entre minúsculas, dígitos, _ y -, y son únicas en tu organización; un duplicado responde 409, así que podés tratar ese caso como "ya existe".

Dale al afiliado un deep link de Telegram que lleve su referencia: https://t.me/<tu_bot>?start=aff-5550001. Cuando alguien lo abre, Telegram le manda a tu bot el mensaje /start aff-5550001. Guardá esa referencia junto al ID de usuario de Telegram del nuevo miembro en tu base de datos: es quien recibe la parte cuando ese miembro pague.

2. Creá la factura con el split del afiliado

Cuando el miembro pide entrar, creá una factura. Poné su ID de usuario de Telegram en merchant_order_id: los webhooks de la factura lo devuelven, así sabés a quién invitar.

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 días',
      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 es el checkout hosteado
}

• Sin afiliado, no mandes splits: tu cuenta platform se queda con todo el neto.
• Una referencia de cuenta desconocida en splits es un 422 en ese campo. Creá primero la cuenta de socio.
• En Live es la misma request sobre BSC_MAINNET con una key Live. Ver Redes y tokens para todos los pares.

3. Abrí el checkout como Mini-App

Agregale ?tg=1 a pay_url y mandalo como botón web_app. Telegram abre el checkout hosteado dentro del chat: el mismo monto, código QR, botón de wallet y estado de confirmación en vivo que /pay/:id, con la acción principal en el MainButton de 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 días: ${invoice.total} ${invoice.token}`,
      reply_markup: {
        inline_keyboard: [[{ text: 'Pagar con USDT', web_app: { url: `${invoice.pay_url}?tg=1` } }]],
      },
    }),
  });
}

Telegram solo permite botones web_app en un chat privado entre el usuario y el bot. En un grupo, mandá un botón url común con pay_url: abre el mismo checkout en el navegador.

4. Mandá la invitación cuando llegue invoice.paid

Suscribí un endpoint a invoice.paid (Developers → Webhooks) y verificá la firma igual que en el receptor del Inicio rápido. Después leé el ID de usuario de Telegram desde merchant_order_id y creá un link de invitación de un solo uso:

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: `Pago recibido. Tu invitación: ${invite.result.invite_link}` }),
  });
}

Hacelo idempotente sobre event.data.invoice_id: una entrega que tu endpoint no responde con 2xx se reintenta, así que el mismo evento puede llegar más de una vez (ver Webhooks). invoice.paid también se dispara para facturas OVERPAID; la diferencia pagada de más queda retenida para que el comprador la reclame (ver Reembolsos).

Entregá solo desde el webhook. Un pago cuenta cuando llega al umbral de confirmaciones de su red; ver Confirmaciones.

5. Pagales a los afiliados

La parte de cada afiliado queda en su saldo de socio. Consultalo con GET /api/v1/crypto/balances y mandalo a su wallet con un 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"
  }'

La key necesita crypto-payouts:create, que solo puede otorgar un usuario con autenticación de dos factores. Cada payout tiene una comisión que sale de amount y un máximo por payout; los dos están en Payouts. También podés hacer el payout desde el dashboard (Payouts → New payout) con un código de tu app de autenticación.

Siguientes pasos

• Ledger y splits: markup, varios socios en una factura y los asientos del ledger.
• Links de pago: una página de precio fijo que podés fijar en un canal, cuando no necesitás atribución por miembro.
• Webhooks: todos los eventos, reintentos y rotación del secreto.