Telegram Bot API

Pagamentos com Telegram Stars em bots: faturas, pre-checkout, reembolsos e assinaturas

· 9 min de leitura

Para receber pagamentos em Telegram Stars no bot, envie uma fatura com sendInvoice usando a moeda XTR e provider_token vazio, responda ao update pre_checkout_query com answerPreCheckoutQuery em até 10 segundos e só entregue o produto depois que chegar a mensagem com successful_payment. Telegram Stars é a moeda obrigatória para produtos e serviços digitais vendidos nos apps do Telegram. Este guia mostra o fluxo completo com um bot funcional em Python e JavaScript e depois cobre reembolsos, histórico de transações, assinaturas e mídia paga.

Como funcionam os pagamentos com Telegram Stars no bot

Telegram Stars são um item virtual dentro do app. O usuário compra Stars via compra no app da Apple ou do Google, ou pelo @PremiumBot, e gasta no seu bot; o formulário de pagamento não pede nenhum dado pessoal. O fluxo:

  1. O bot envia uma fatura: sendInvoice para um chat ou createInvoiceLink para gerar um link.
  2. O usuário toca em Pagar (comprando Stars antes, se precisar).
  3. O bot recebe um update com pre_checkout_query.
  4. O bot confirma ou recusa o pedido com answerPreCheckoutQuery, em até 10 segundos.
  5. O Telegram envia uma mensagem de serviço com successful_payment.
  6. O bot guarda o telegram_payment_charge_id e entrega o produto.

Produtos digitais devem ser vendidos em Stars. O Telegram determina que bots e Mini Apps usem Telegram Stars para vender produtos e serviços digitais dentro dos apps do Telegram, independentemente de site ou provedor de pagamento que você tenha em outro lugar; caso contrário, o Telegram não pode exibir o bot para usuários de celular. Outras moedas e provedores são só para produtos físicos, que seguem um fluxo separado com provider token.

Enviar uma fatura com sendInvoice e XTR

Uma fatura mínima de 50 Stars:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendInvoice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "title": "Pacote Pro",
    "description": "50 gerações de imagem extras para a sua conta",
    "payload": "pro-pack-v1",
    "provider_token": "",
    "currency": "XTR",
    "prices": [{"label": "Pacote Pro", "amount": 50}]
  }'

O método devolve a Message enviada. Parâmetros que importam para Stars:

ParâmetroRegra para Telegram Stars
titleNome do produto, 1–32 caracteres.
descriptionDescrição do produto, 1–255 caracteres.
payload1–128 bytes, não é mostrado ao usuário. Coloque aqui o id do pedido ou do produto; ele volta no pre-checkout e no pagamento.
provider_tokenOpcional; passe string vazia para Stars.
currencyXTR.
pricesArray de LabeledPrice que precisa ter exatamente um item; amount é o preço em Stars (inteiro).
start_parameterVazio: cópias encaminhadas mantêm o botão Pagar. Preenchido: cópias encaminhadas mostram um botão de URL com deep link para o bot.
photo_urlImagem opcional do produto, com photo_size, photo_width, photo_height.

Gorjetas (max_tip_amount) não são suportadas em Stars, e need_name, need_email, need_shipping_address, is_flexible e campos parecidos são ignorados. Se você passar um reply_markup próprio, o primeiro botão precisa ser de pagamento ("pay": true); os trechos ⭐ e XTR no texto dele viram o ícone da Star. Faturas podem ir para chats privados, grupos e canais. Teste sem código: abra o sendInvoice no Bot API Tester, preencha os campos acima e mande uma fatura para você mesmo.

O createInvoiceLink recebe os mesmos title, description, payload, currency e prices, mas em vez de enviar uma mensagem devolve o link da fatura como string. Abra-o numa Mini App com Telegram.WebApp.openInvoice(url) ou compartilhe como link comum. É também o método usado para assinaturas (veja abaixo).

Responder ao pre_checkout_query em até 10 segundos

Quando o usuário toca em Pagar, o bot recebe um PreCheckoutQuery com id, from, currency, total_amount e invoice_payload. A resposta precisa sair em até 10 segundos, senão a transação é cancelada:

Mantenha esse handler rápido: confira o payload e o estoque, responda e deixe o resto para depois. Aprovar a consulta não significa que o dinheiro entrou.

Entregar após o successful_payment

Um pagamento bem-sucedido chega como message cujo campo successful_payment traz currency, total_amount, invoice_payload e telegram_payment_charge_id. A regra do Telegram é clara: sempre confirme que recebeu o successful_payment antes de entregar. Salve o telegram_payment_charge_id junto com o user id do comprador, porque o reembolso exige os dois.

Exemplo completo: um bot que vende por Telegram Stars

Este bot com long polling envia uma fatura no /buy, valida o pre-checkout, registra o pagamento e responde ao /paysupport. Atenção ao allowed_updates: se você restringe os tipos de update, inclua pre_checkout_query, senão os pagamentos nunca chegam ao bot.

import json
import os
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
PAYLOAD = "pro-pack-v1"
PRICE = 50  # em Telegram Stars


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def handle(update):
    query = update.get("pre_checkout_query")
    if query:
        ok = (query["invoice_payload"] == PAYLOAD and query["currency"] == "XTR"
              and query["total_amount"] == PRICE)
        answer = {"pre_checkout_query_id": query["id"], "ok": ok}
        if not ok:
            answer["error_message"] = "Esta oferta expirou. Mande /buy para receber uma nova fatura."
        call("answerPreCheckoutQuery", **answer)  # em até 10 segundos
        return

    msg = update.get("message")
    if not msg:
        return
    chat_id = msg["chat"]["id"]
    if "successful_payment" in msg:
        payment = msg["successful_payment"]
        with open("payments.jsonl", "a") as f:  # guarde o charge id para reembolsos
            f.write(json.dumps({"user_id": msg["from"]["id"],
                                "charge_id": payment["telegram_payment_charge_id"],
                                "payload": payment["invoice_payload"],
                                "amount": payment["total_amount"]}) + "\n")
        call("sendMessage", chat_id=chat_id, text="Obrigado! Seu Pacote Pro está ativo.")
    elif msg.get("text") == "/buy":
        call("sendInvoice", chat_id=chat_id, title="Pacote Pro",
             description="50 gerações de imagem extras para a sua conta",
             payload=PAYLOAD, provider_token="", currency="XTR",
             prices=[{"label": "Pacote Pro", "amount": PRICE}])
    elif msg.get("text") == "/paysupport":
        call("sendMessage", chat_id=chat_id,
             text="Problema com o pagamento? Descreva em uma mensagem e respondemos em até 24 horas.")


offset = 0
while True:
    updates = call("getUpdates", offset=offset, timeout=30,
                   allowed_updates=["message", "pre_checkout_query"])
    for update in updates:
        offset = update["update_id"] + 1
        handle(update)
import { appendFile } from "node:fs/promises";

const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const PAYLOAD = "pro-pack-v1";
const PRICE = 50; // em Telegram Stars

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

async function handle(update) {
  const query = update.pre_checkout_query;
  if (query) {
    const ok = query.invoice_payload === PAYLOAD && query.currency === "XTR"
      && query.total_amount === PRICE;
    const answer = { pre_checkout_query_id: query.id, ok };
    if (!ok) answer.error_message = "Esta oferta expirou. Mande /buy para receber uma nova fatura.";
    await call("answerPreCheckoutQuery", answer); // em até 10 segundos
    return;
  }

  const msg = update.message;
  if (!msg) return;
  const chatId = msg.chat.id;
  if (msg.successful_payment) {
    const payment = msg.successful_payment;
    await appendFile("payments.jsonl", JSON.stringify({ // guarde o charge id para reembolsos
      user_id: msg.from.id,
      charge_id: payment.telegram_payment_charge_id,
      payload: payment.invoice_payload,
      amount: payment.total_amount,
    }) + "\n");
    await call("sendMessage", { chat_id: chatId, text: "Obrigado! Seu Pacote Pro está ativo." });
  } else if (msg.text === "/buy") {
    await call("sendInvoice", {
      chat_id: chatId, title: "Pacote Pro",
      description: "50 gerações de imagem extras para a sua conta",
      payload: PAYLOAD, provider_token: "", currency: "XTR",
      prices: [{ label: "Pacote Pro", amount: PRICE }],
    });
  } else if (msg.text === "/paysupport") {
    await call("sendMessage", {
      chat_id: chatId,
      text: "Problema com o pagamento? Descreva em uma mensagem e respondemos em até 24 horas.",
    });
  }
}

let offset = 0;
while (true) {
  const updates = await call("getUpdates", {
    offset, timeout: 30, allowed_updates: ["message", "pre_checkout_query"],
  });
  for (const update of updates) {
    offset = update.update_id + 1;
    await handle(update);
  }
}

Salve a versão JavaScript como bot.mjs (Node.js 18+). Em produção, use um banco de dados de verdade e torne a entrega idempotente por telegram_payment_charge_id. Com webhook o handler é o mesmo; veja webhook do bot do Telegram para a configuração e o allowed_updates.

Reembolsar com refundStarPayment

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/refundStarPayment" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 123456789, "telegram_payment_charge_id": "CHARGE_ID_DO_SUCCESSFUL_PAYMENT"}'

Em caso de sucesso devolve true, as Stars voltam para o usuário e o chat recebe uma mensagem de serviço com refunded_payment. Revogue o que você entregou. Se o comprador abrir um chargeback com a Apple ou o Google, as Stars reembolsadas são descontadas do saldo do bot; o Telegram diz que isso foge do controle dele.

Saldo e transações: getMyStarBalance, getStarTransactions

Assinaturas em Telegram Stars

Passe subscription_period no createInvoiceLink para cobrar o usuário a cada 30 dias:

Para acesso pago a um canal existe o createChatSubscriptionInviteLink, com subscription_period 2592000 e subscription_price de 1–10000 Stars; o bot precisa do direito de admin can_invite_users.

O sendPaidMedia envia até 10 fotos ou vídeos bloqueados por um preço: star_count de 1–25000 e um payload opcional de 0–128 bytes. Num canal, a receita vai para o saldo do canal; nos demais chats, para o do bot. Se o payload não estiver vazio e o chat não for um canal, o bot recebe um update purchased_paid_media com o comprador e o payload — então inclua-o no allowed_updates se você filtra updates.

Testar pagamentos em Stars no ambiente de testes

O Telegram permite testar pagamentos em Stars de graça no seu ambiente de testes: crie lá uma conta de teste e um bot e mande as requisições para https://api.telegram.org/bot<token>/test/METHOD_NAME. O nosso tester tem uma chave TEST para isso. O passo a passo está em servidor de testes do Telegram. Para entrar no ar, passe o bot para o ambiente de produção.

Checklist de lançamento e problemas comuns

Começando agora com bots? Veja como criar um bot no Telegram. A referência oficial está na documentação de pagamentos com Telegram Stars e na seção Payments da Bot API.

Perguntas frequentes

Como receber pagamentos em Telegram Stars num bot?

Envie uma fatura com sendInvoice (ou createInvoiceLink) usando currency XTR, provider_token vazio e exatamente um item em prices. Responda ao update pre_checkout_query com answerPreCheckoutQuery em até 10 segundos e entregue o produto quando chegar a mensagem com successful_payment.

Preciso de provider token para Telegram Stars?

Não. O provider_token só é necessário para produtos físicos e serviços. Para pagamentos em Telegram Stars, passe uma string vazia ou omita o parâmetro.

Posso vender produtos digitais no bot em reais, cartão ou cripto?

Não. Segundo o Telegram, produtos e serviços digitais vendidos dentro dos apps do Telegram devem ser pagos exclusivamente em Telegram Stars, por causa das regras da App Store e do Google Play. Outras moedas e provedores só valem para produtos físicos e serviços.

Como reembolsar um pagamento em Telegram Stars?

Chame refundStarPayment com o user_id do comprador e o telegram_payment_charge_id da mensagem successful_payment. Guarde esse id de todo pagamento, senão não dá para reembolsar depois.

Como funcionam as assinaturas em Telegram Stars nos bots?

Crie um link de fatura com createInvoiceLink e subscription_period = 2592000 (30 dias, hoje o único valor permitido); o preço não pode passar de 10000 Stars. As renovações chegam como successful_payment com is_recurring, e o editUserStarSubscription cancela ou reativa a renovação.

Como testar pagamentos em Telegram Stars de graça?

Use o ambiente de testes do Telegram: crie lá uma conta de teste e um bot e chame a API em /bot<token>/test/METHOD_NAME. Segundo o Telegram, os pagamentos em Stars podem ser testados ali livremente.

Como criar um bot no Telegram grátis: do BotFather à primeira mensagem

Aprenda a criar bot no Telegram grátis com o @BotFather: pegue o token, teste com getMe e envie a primeira mensagem com curl e Python.

Como hospedar um bot do Telegram: deploy em VPS, Docker e serverless

Como hospedar e fazer deploy de um bot do Telegram: polling ou webhook, serviço systemd na VPS, Docker, Cloudflare Workers com secret_token e checklist.

Telegram Bot API 10.0–10.5: configurações do bot, widgets, rich messages, mensagens efêmeras, guest mode e mais

Novidades do Telegram Bot API 10.0–10.5: setMySettings e BotFullInfo, widgets HTML, rich messages, mensagens efêmeras e guest mode, com exemplos JSON.

Erros do Telegram Bot API: o que cada erro significa e como resolver

Erros do Telegram Bot API explicados: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Causas, soluções e código pronto.

Limites do Telegram Bot API: rate limit, erro 429, tamanho de arquivos e de mensagens

Rate limit do Telegram Bot API na prática: 30 msg/s, 1 msg/s por chat, 20/min em grupos, como tratar 429 e retry_after, limites de arquivo e de texto.

Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start

Configure os comandos do bot do Telegram: /setcommands no @BotFather, setMyCommands com escopos e idiomas, parâmetro do /start e /cmd@bot em grupos.

Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard

Botões no bot do Telegram: inline keyboard com callback_data, answerCallbackQuery, editar a mensagem após o clique, reply keyboard e ForceReply.

Integração n8n + Telegram: conecte o bot, dispare workflows e envie mensagens

Conecte o n8n ao Telegram: token do bot como Access Token, webhook do Telegram Trigger com HTTPS público, envio por chat id e soluções para erros comuns.

Como enviar mensagens pela API do Telegram com sendMessage (curl, Python e JavaScript)

Use a API do Telegram para enviar mensagens com sendMessage: exemplos em curl, Python e JavaScript, HTML e MarkdownV2, botões inline e erros comuns.

Telegram bot token: como pegar o token do bot, verificar e revogar

Veja como pegar o token do bot do Telegram no @BotFather, achar o token de um bot existente, testar com getMe e revogar um token vazado.

Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n

Configure o webhook do bot do Telegram: requisitos de HTTPS e portas, setWebhook com secret_token, getWebhookInfo, deleteWebhook e erros comuns no n8n.

Chat id do Telegram: como pegar o ID de usuário, grupo, canal e tópico com o seu bot

Descubra o chat id do Telegram para o seu bot: getUpdates em chat privado, grupos, supergrupos (-100), canais e tópicos, e o que fazer se vier vazio.

Bot inline no Telegram: como ativar o modo inline e responder às consultas

Crie um bot inline no Telegram: ative o modo inline no @BotFather ou com setMySettings, trate updates inline_query e responda com answerInlineQuery.

Servidor de teste do Telegram: como testar um bot no ambiente de teste

Use o servidor de teste do Telegram: entre no ambiente de teste, crie um bot de teste, chame a Bot API via /test/ e ative o modo TEST no nosso tester.

Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar

Telegram no seu site: novo login com Telegram (OIDC), Login Widget clássico com checagem do hash, post incorporado, comentários e botão compartilhar.

API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites

Referência da API JavaScript TelegramWidget: propriedades, request(), eventos, códigos de erro, variáveis CSS, widget_query, answerWidgetQuery e limites.

Exemplos de widget do Telegram: HTML completo e bot em Python

Exemplos de widget do Telegram com código completo: card de pedido, contador com widget_query, enquete compartilhada ao vivo e prévia no navegador.

Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot

Widgets do Telegram (Bot API 10.4): o que são, como funcionam sendWidget, chat_data e public_data, onde já rodam e a diferença para Mini Apps.

Como testar uma Mini App do Telegram: do mock no navegador ao app real

Teste sua Mini App do Telegram passo a passo: modo mock no navegador, localhost via túnel HTTPS, ambiente de testes, DevTools e validação do initData.