Receita: bot do Telegram

O bot nunca vê dinheiro. Com /buy, ele envia ao usuário o próprio link para uma fatura; o seu servidor ouve invoice.fulfilled e libera o acesso. Cada comando pago pergunta ao Perly Pay, então nada se perde ao reiniciar. O Discord funciona igual, com um cargo.

Como funciona

1. 1

   Produto e preço

   Único ou vitalício para “para sempre”, por prazo para passes, assinatura para assinaturas renovadas por fatura.

2. 2

   Um cliente por usuário do chat

   external_id: "tg:<user id>". Peça o e-mail só para assinaturas: as renovações vão para ele.

3. 3

   /buy

   Uma fatura com o id do chat em metadata, enviada com um botão. Uma fatura por usuário por dia, graças a uma chave de idempotência.

4. 4

   Libere o acesso

   Com invoice.fulfilled, pegue o id do chat em metadata e responda: uma mensagem, um convite de uso único, um cargo.

5. 5

   Comandos pagos

   entitlements.check({ customer_external_id: "tg:<id>", product }).

const invoice = await pay.invoices.create(
  { line_items: [{ price: PRICE }], customer: customer.id, metadata: { chat_id: String(chatId) } },
  { idempotencyKey: `buy-${userId}-${today}` },
);
await tg("sendMessage", { chat_id: chatId, text: "Pay:", reply_markup: { inline_keyboard: [[{ text: "Pay", url: invoice.url }]] } });

Execute o exemplo

1. 1

   Instale

   npm install em examples/telegram-bot (Node 20.12+).

2. 2

   Chave

   Copie .env.example para .env e coloque uma chave de teste (sk_test_…) em PERLY_PAY_SECRET_KEY.

3. 3

   Prepare

   npm run setup cria o produto e o preço com a sua chave e imprime os ids deles para o .env.

4. 4

   Execute

   npm start (ou npm run dev), como diz o README dele.

5. 5

   Pague sem carteira

   Mande /buy para o bot, abra o Pay e clique em Simulate payment: o bot diz “Payment confirmed” e /secret responde.

Erros comuns

• Um mesmo link de pagamento para todos: não dá para ver quem pagou. Uma fatura por usuário, com o id do chat.
• Liberar o acesso quando o usuário toca em “Já paguei”. Só o webhook ou entitlements.check liberam.
• O acesso na memória do bot. Ele se perde ao reiniciar; pergunte ao Perly Pay.