Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅
要在 Telegram 机器人中接收 Stars 支付,只需三步:用 sendInvoice 发送发票(货币 XTR,provider_token 留空),在 10 秒内用 answerPreCheckoutQuery 回应 pre_checkout_query 更新,等收到带有 successful_payment 的消息后再发货。在 Telegram 应用内出售数字商品和服务,必须使用 Telegram Stars。本文用一个可运行的 Python 和 JavaScript 机器人演示完整流程,并介绍退款、交易记录、订阅和付费媒体。
Telegram 机器人 Stars 支付的流程
Telegram Stars 是应用内的虚拟道具。用户通过 Apple 或 Google 的应用内购买,或者通过 @PremiumBot 购买 Stars,再在你的机器人里消费;支付表单不需要填写任何个人信息。流程如下:
- 机器人发送发票:用
sendInvoice发到聊天中,或用createInvoiceLink生成链接。 - 用户点击 Pay(余额不足时先购买 Stars)。
- 机器人收到带有
pre_checkout_query的更新。 - 机器人在 10 秒内用
answerPreCheckoutQuery确认或拒绝订单。 - Telegram 发送一条带有
successful_payment的服务消息。 - 机器人保存
telegram_payment_charge_id并发货。
数字商品必须用 Stars 出售。Telegram 明确规定:机器人或 Mini App 在 Telegram 应用内出售数字商品和服务时必须使用 Telegram Stars,无论你在其他地方是否有自己的网站或支付渠道;否则 Telegram 无法向移动端用户展示你的机器人。其他货币和支付服务商只适用于实体商品,那是另一套使用 provider token 的流程。
用 sendInvoice 和 XTR 发送发票
一张最简单的 50 Stars 发票:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendInvoice" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"title": "Pro 套餐",
"description": "为你的账号增加 50 次图片生成额度",
"payload": "pro-pack-v1",
"provider_token": "",
"currency": "XTR",
"prices": [{"label": "Pro 套餐", "amount": 50}]
}'
该方法返回已发送的 Message。与 Stars 相关的参数:
| 参数 | Telegram Stars 的规则 |
|---|---|
title | 商品名称,1–32 个字符。 |
description | 商品描述,1–255 个字符。 |
payload | 1–128 字节,不会展示给用户。可以放订单号或商品 ID,它会在预结账查询和付款消息中原样返回。 |
provider_token | 可选;Stars 支付传空字符串。 |
currency | XTR。 |
prices | LabeledPrice 数组,必须只包含一项;amount 是以 Stars 计的价格(整数)。 |
start_parameter | 为空:转发的副本保留 Pay 按钮。不为空:转发的副本改为显示一个带机器人深层链接的 URL 按钮。 |
photo_url | 可选的商品图片,配合 photo_size、photo_width、photo_height 使用。 |
Stars 不支持小费(max_tip_amount),need_name、need_email、need_shipping_address、is_flexible 等字段也会被忽略。如果自己添加 reply_markup,第一个按钮必须是 Pay 按钮("pay": true),按钮文字中的 ⭐ 和 XTR 会被替换成星星图标。发票可以发到私聊、群组和频道。不写代码也能试:在 Bot API Tester 中打开 sendInvoice,填好上面的字段,给自己发一张发票。
createInvoiceLink:用于 Mini App 和网站
createInvoiceLink 接受同样的 title、description、payload、currency 和 prices,但不会发送消息,而是以字符串形式返回发票链接。可以在 Mini App 中用 Telegram.WebApp.openInvoice(url) 打开,也可以当作普通链接分享。订阅同样通过这个方法创建(见下文)。
在 10 秒内回应 pre_checkout_query
用户点击 Pay 后,机器人会收到一个 PreCheckoutQuery,包含 id、from、currency、total_amount 和 invoice_payload。必须在 10 秒内回应,否则交易会被取消:
ok: true:商品可售,你已准备好履行订单。ok: false并附上error_message:一段用户能看懂的原因,Telegram 会展示给用户,例如“该优惠已过期,请发送 /buy 获取新发票”。
这个处理函数要尽量快:检查 payload 和库存,回应,其余工作稍后再做。确认预结账查询并不代表钱已经到账。
收到 successful_payment 后再发货
付款成功后会收到一条 message,其中 successful_payment 字段包含 currency、total_amount、invoice_payload 和 telegram_payment_charge_id。Telegram 的规定很明确:发货前务必确认已收到 successful_payment。把 telegram_payment_charge_id 和买家的 user id 一起保存,退款时两者都要用到。
完整示例:用 Telegram Stars 卖东西的机器人
这个长轮询机器人收到 /buy 时发送发票,校验预结账查询,记录付款,并响应 /paysupport。注意 allowed_updates:如果限制了更新类型,一定要包含 pre_checkout_query,否则付款请求永远到不了机器人。
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 # 单位: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"] = "该优惠已过期,请发送 /buy 获取新发票。"
call("answerPreCheckoutQuery", **answer) # 必须在 10 秒内回应
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: # 保存 charge id,退款时要用
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="感谢购买!你的 Pro 套餐已生效。")
elif msg.get("text") == "/buy":
call("sendInvoice", chat_id=chat_id, title="Pro 套餐",
description="为你的账号增加 50 次图片生成额度",
payload=PAYLOAD, provider_token="", currency="XTR",
prices=[{"label": "Pro 套餐", "amount": PRICE}])
elif msg.get("text") == "/paysupport":
call("sendMessage", chat_id=chat_id,
text="付款遇到问题?请用一条消息描述情况,我们会在 24 小时内回复。")
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; // 单位: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 = "该优惠已过期,请发送 /buy 获取新发票。";
await call("answerPreCheckoutQuery", answer); // 必须在 10 秒内回应
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({ // 保存 charge id,退款时要用
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: "感谢购买!你的 Pro 套餐已生效。" });
} else if (msg.text === "/buy") {
await call("sendInvoice", {
chat_id: chatId, title: "Pro 套餐",
description: "为你的账号增加 50 次图片生成额度",
payload: PAYLOAD, provider_token: "", currency: "XTR",
prices: [{ label: "Pro 套餐", amount: PRICE }],
});
} else if (msg.text === "/paysupport") {
await call("sendMessage", {
chat_id: chatId,
text: "付款遇到问题?请用一条消息描述情况,我们会在 24 小时内回复。",
});
}
}
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);
}
}把 JavaScript 版本保存为 bot.mjs(Node.js 18+)。正式环境请使用真正的数据库,并按 telegram_payment_charge_id 保证发货的幂等性。改用 Webhook 时处理逻辑不变,设置方法和 allowed_updates 参见 Telegram Bot Webhook 设置教程。
用 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_FROM_SUCCESSFUL_PAYMENT"}'
成功时返回 true,Stars 退回给用户,聊天中会出现一条带有 refunded_payment 的服务消息。别忘了收回已发放的商品。另外,如果买家向 Apple 或 Google 发起拒付(chargeback),退回的 Stars 会从机器人余额中扣除;Telegram 表示这不在它的控制范围内。
余额与交易记录:getMyStarBalance、getStarTransactions
getMyStarBalance不需要参数,以StarAmount返回机器人当前的余额。getStarTransactions按时间顺序返回StarTransactions,用offset和limit(1–100,默认 100)分页。对于用户的入账付款,StarTransaction.id等于telegram_payment_charge_id,source描述付款方,可以用来和自己的记录对账。
Telegram Stars 订阅
在 createInvoiceLink 中传入 subscription_period,即可每 30 天向用户扣费一次:
currency必须是XTR,subscription_period目前只能是2592000(30 天)。- 订阅价格不能超过 10000 Stars。一个机器人可以有任意多个有效订阅,同一个用户也可以订阅多个。
- 每次扣费都以
successful_payment的形式到达:is_first_recurring表示首次付款,is_recurring表示续费,subscription_expiration_date表示已付费的访问截止时间。 - 调用
editUserStarSubscription并传入user_id、telegram_payment_charge_id和is_canceled: true可停止续订(用户在已付费周期结束前仍可使用);is_canceled: false可恢复被机器人取消的订阅。
如果要做付费频道,可以使用 createChatSubscriptionInviteLink,传入 subscription_period 2592000 和 1–10000 Stars 的 subscription_price;机器人需要拥有 can_invite_users 管理员权限。
付费媒体简介
sendPaidMedia 可以发送最多 10 张图片或视频,付费后才能查看:star_count 为 1–25000,可选 payload 为 0–128 字节。在频道中发送时收入进入频道余额,其他情况下进入机器人余额。如果 payload 不为空且聊天不是频道,机器人会收到带有买家和 payload 的 purchased_paid_media 更新;如果你过滤了更新类型,记得把它加入 allowed_updates。
在测试环境中测试 Stars 支付
Telegram 允许在专门的测试环境中免费测试 Stars 支付:在那里创建测试账号和机器人,然后把 API 请求发往 https://api.telegram.org/bot<token>/test/METHOD_NAME。我们的测试工具也有一个 TEST 开关,作用相同。详细步骤见 Telegram 测试服务器教程。准备上线时,再把机器人切换到正式环境。
上线检查清单与常见问题
- 点击 Pay 后付款被取消:机器人没有在 10 秒内回应
pre_checkout_query。检查allowed_updates是否包含它,以及回应前是否执行了耗时操作。 - 发票被拒绝:Stars 发票的
prices必须只有一项,currency必须是XTR,且不支持小费。查看错误响应中的description。 - 没付款就发了货:只在收到
successful_payment后发货,绝不能在预结账阶段发货。 - 多个买家支付了同一张发票:被转发的发票和群组中的发票可以被多次支付。如果订单不能重复履行,就在预结账阶段拒绝多余的付款。
- 客服与条款:Telegram 要求机器人响应
/paysupport,并建议提供/terms命令;Telegram 官方客服无法处理通过你的机器人完成的购买问题。 - 账号与数据安全:为拥有机器人的账号开启两步验证,并备份付款记录。
刚开始接触机器人?请先阅读创建 Telegram 机器人教程。官方参考资料见 Telegram Stars 支付文档和 Bot API 的 Payments 章节。
常见问题
Telegram 机器人怎样接收 Stars 付款?
调用 sendInvoice(或 createInvoiceLink)发送发票,currency 设为 XTR,provider_token 留空,prices 中只放一项。收到 pre_checkout_query 更新后在 10 秒内用 answerPreCheckoutQuery 回应,等到带有 successful_payment 的消息到达后再发货。
使用 Telegram Stars 需要 provider token 吗?
不需要。provider_token 只用于实体商品和服务。用 Telegram Stars 收款时传空字符串或干脆不传。
机器人里的数字商品可以用美元、银行卡或加密货币收款吗?
不可以。按照 Telegram 的规定,由于 App Store 和 Google Play 的规则,在 Telegram 应用内出售的数字商品和服务只能用 Telegram Stars 支付。其他货币和支付服务商只允许用于实体商品和服务。
怎样退还 Telegram Stars 付款?
调用 refundStarPayment,传入买家的 user_id 和 successful_payment 消息中的 telegram_payment_charge_id。每笔付款都要保存这个 ID,否则以后无法退款。
机器人的 Telegram Stars 订阅是怎么运作的?
用 createInvoiceLink 创建发票链接,并传入 subscription_period = 2592000(30 天,目前唯一允许的值);价格不能超过 10000 Stars。续费以带 is_recurring 的 successful_payment 形式到达,editUserStarSubscription 可以取消或恢复续订。
怎样免费测试 Telegram Stars 支付?
使用 Telegram 专门的测试环境:在那里创建测试账号和机器人,通过 /bot<token>/test/METHOD_NAME 调用 API。Telegram 表示可以在测试环境中免费测试 Stars 支付。
相关教程
Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息
Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。
Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案
Telegram 机器人部署与托管指南:轮询还是 Webhook,VPS 上的 systemd 服务、Docker 部署、带 secret_token 校验的 Cloudflare Workers,以及上线检查清单。
Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等
Telegram Bot API 10.0–10.5 更新了什么:setMySettings 与 BotFullInfo、HTML 小组件、富文本消息、临时消息、访客模式,附 JSON 示例与升级清单。
Telegram Bot API 错误码大全:每种报错的含义与解决方法
Telegram Bot API 常见错误详解:400 chat not found、403 bot was blocked by the user、409 Conflict、429 retry_after,逐一说明原因、解决方法,并附错误处理代码。
Telegram Bot API 限制汇总:发送频率、429 错误、文件大小与消息长度
Telegram Bot API 频率限制详解:每秒约 30 条、单聊每秒 1 条、群组每分钟 20 条,429 错误与 retry_after 处理代码,以及文件大小和消息长度限制。
Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接
Telegram 机器人命令配置教程:@BotFather /setcommands、按作用域和语言调用 setMyCommands、/start 深层链接参数,以及群组中的 /cmd@bot 用法。
Telegram 机器人键盘教程:内联键盘、回调按钮与回复键盘
Telegram 机器人按钮教程:用 callback_data 创建内联键盘、answerCallbackQuery 应答、点击后编辑消息,以及回复键盘和 ForceReply,附完整 Python 与 JS 示例。
n8n Telegram 集成教程:连接机器人、触发工作流并发送消息
n8n 对接 Telegram 机器人:把 bot token 填入 Access Token,Telegram Trigger 通过公网 HTTPS Webhook 接收消息,按 chat id 发送消息,以及常见报错的解决方法。
Telegram Bot API 发送消息教程:sendMessage 参数、格式、按钮与错误处理
Telegram Bot API 发送消息中文教程:sendMessage 参数说明,curl、Python、JavaScript 示例,HTML 与 MarkdownV2 格式、内联按钮、群组和频道发送,以及 400、403、429 错误处理。
Telegram Bot Token 怎么获取:获取、查看、验证和撤销机器人 Token
Telegram Bot Token 怎么获取?用 @BotFather 的 /newbot 获取新 Token,在 /mybots 中查看已有 Token,用 getMe 检查是否有效,泄露后及时撤销,并配合 chat_id 接入 n8n 等工具。
Telegram Bot Webhook 设置教程:用 setWebhook 配置 Webhook URL 和 secret_token
Telegram Bot API setWebhook 中文教程:Webhook URL 的 HTTPS 与端口要求、secret_token 请求头校验、用 getWebhookInfo 排错、用 deleteWebhook 切回轮询,以及 409 等常见错误的解决方法。
Telegram chat id 获取教程:查看用户、群组、频道和话题的聊天 ID
Telegram chat id 获取教程:用 getUpdates 查看私聊、群组、超级群组、频道和论坛话题的聊天 ID,讲清负数和 -100 前缀的含义,并排查 result 为空、409 Conflict 等常见问题,附 Python 示例。
Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询
Telegram 内联机器人(inline bot)开发教程:用 @BotFather 或 setMySettings 开启 Inline 模式,处理 inline_query 更新,并通过 answerInlineQuery 返回结果。
Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人
Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 Telegram 机器人。
Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮
在网站上接入 Telegram:新版 Telegram 登录(OpenID Connect)、旧版 Login Widget 及 hash 校验代码、嵌入 Telegram 帖子、评论区小部件和分享按钮,附常见问题排查。
TelegramWidget JavaScript API:属性、事件、错误码与限制参考
TelegramWidget JavaScript API 中文参考:属性、request()、事件、错误码、CSS 变量,widget_query 与 answerWidgetQuery 的用法,以及小组件的全部限制。
Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码
可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。
Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML
Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。
Telegram Mini App 测试教程:从浏览器模拟到真实 Telegram 客户端
Telegram Mini App 测试全流程:浏览器模拟模式、通过 HTTPS 隧道在 localhost 调试、测试环境、各平台打开 DevTools 的方法,以及服务器端 initData 校验代码。