Pagamentos com Telegram Stars em bots: faturas, pre-checkout, reembolsos e assinaturas
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:
- O bot envia uma fatura:
sendInvoicepara um chat oucreateInvoiceLinkpara gerar um link. - O usuário toca em Pagar (comprando Stars antes, se precisar).
- O bot recebe um update com
pre_checkout_query. - O bot confirma ou recusa o pedido com
answerPreCheckoutQuery, em até 10 segundos. - O Telegram envia uma mensagem de serviço com
successful_payment. - O bot guarda o
telegram_payment_charge_ide 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âmetro | Regra para Telegram Stars |
|---|---|
title | Nome do produto, 1–32 caracteres. |
description | Descrição do produto, 1–255 caracteres. |
payload | 1–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_token | Opcional; passe string vazia para Stars. |
currency | XTR. |
prices | Array de LabeledPrice que precisa ter exatamente um item; amount é o preço em Stars (inteiro). |
start_parameter | Vazio: 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_url | Imagem 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.
createInvoiceLink para Mini Apps e sites
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:
ok: truese o produto está disponível e você pode atender o pedido.ok: falsecomerror_message, um motivo legível que o Telegram mostra ao usuário, por exemplo "Esta oferta expirou, mande /buy para receber uma nova fatura".
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
getMyStarBalancenão recebe parâmetros e devolve o saldo atual do bot comoStarAmount.getStarTransactionsdevolveStarTransactionsem ordem cronológica; pagine comoffsetelimit(1–100, padrão 100). Em pagamentos recebidos de usuários,StarTransaction.idé igual aotelegram_payment_charge_id, esourcedescreve o pagador, o que permite conciliar os seus registros.
Assinaturas em Telegram Stars
Passe subscription_period no createInvoiceLink para cobrar o usuário a cada 30 dias:
currencyprecisa serXTR, esubscription_periodhoje precisa ser sempre2592000(30 dias).- O preço da assinatura não pode passar de 10000 Stars. Um bot pode ter qualquer número de assinaturas ativas, até várias do mesmo usuário.
- Cada cobrança chega como
successful_payment:is_first_recurringmarca o primeiro pagamento,is_recurringmarca as renovações esubscription_expiration_datediz até quando o acesso está pago. editUserStarSubscriptioncomuser_id,telegram_payment_charge_ideis_canceled: trueinterrompe a renovação (o usuário mantém o acesso até o fim do período pago);is_canceled: falsereativa uma assinatura que o bot cancelou.
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.
Mídia paga em resumo
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
- Pagamento cancelado depois de tocar em Pagar: o bot não respondeu ao
pre_checkout_queryem 10 segundos. Confira se oallowed_updateso inclui e se nenhum trabalho lento roda antes da resposta. - Fatura recusada: em Stars,
pricesprecisa ter exatamente um item,currencyprecisa serXTRe gorjetas não são suportadas. Leia odescriptionda resposta de erro. - Produto entregue sem pagamento: entregue no
successful_payment, nunca no pre-checkout. - Vários compradores pagaram a mesma fatura: faturas encaminhadas e de grupo podem ser pagas várias vezes. Recuse pagamentos extras no pre-checkout se o pedido não puder ser atendido duas vezes.
- Suporte e termos: o Telegram exige que o bot responda ao
/paysupporte recomenda um comando/terms; o suporte do Telegram não ajuda usuários com compras feitas no seu bot. - Conta e dados: ative a verificação em duas etapas na conta dona do bot e faça backup dos registros de pagamento.
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.
Guias relacionados
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.