Telegram Bot API

Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅

· 9 分钟阅读

要在 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,再在你的机器人里消费;支付表单不需要填写任何个人信息。流程如下:

  1. 机器人发送发票:用 sendInvoice 发到聊天中,或用 createInvoiceLink 生成链接。
  2. 用户点击 Pay(余额不足时先购买 Stars)。
  3. 机器人收到带有 pre_checkout_query 的更新。
  4. 机器人在 10 秒内用 answerPreCheckoutQuery 确认或拒绝订单。
  5. Telegram 发送一条带有 successful_payment 的服务消息。
  6. 机器人保存 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 个字符。
payload1–128 字节,不会展示给用户。可以放订单号或商品 ID,它会在预结账查询和付款消息中原样返回。
provider_token可选;Stars 支付传空字符串。
currencyXTR。
pricesLabeledPrice 数组,必须只包含一项;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 接受同样的 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 秒内回应,否则交易会被取消:

这个处理函数要尽量快:检查 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

Telegram Stars 订阅

在 createInvoiceLink 中传入 subscription_period,即可每 30 天向用户扣费一次:

如果要做付费频道,可以使用 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 测试服务器教程。准备上线时,再把机器人切换到正式环境。

上线检查清单与常见问题

刚开始接触机器人?请先阅读创建 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 校验代码。