面向开发者的 PayStars API:在机器人中销售 Stars 和 Premium 的完整流程
以集成方案的形式讲解 PayStars REST API:X-API-Key、用户名校验、USD 报价与 max_usd、幂等订单、409 price_changed 错误以及 TxId 核验。
发布于: · 更新于:

想在自己的机器人、商店或应用里销售 Telegram Stars 和 Premium?PayStars API 提供统一的 HTTPS 接口,以及与网站共享的 USD 余额。本文不重复 API 文档,而是说明如何从头到尾搭建集成。
架构概览
你的系统只做三件事:用 USDT 充值余额、查询价格、创建订单。通过 Telegram 官方购买流程完成交付由 PayStars 负责。
| 组成 | 作用 |
|---|---|
| 访问 | X-API-Key 请求头,密钥在后台创建 |
| 余额 | USD,用 USDT(TON、BEP20 或 TRC20)充值 |
| 价格 | Fragment 价格 × 1.05,向上取整到美分 |
| 限速 | 每个密钥每秒 10 次 |
| 透明度 | 每个完成订单都有公开 TxId |
第一步:充值余额
向 POST /usd/invoice 发送金额和链(chain:"ton"、"bsc" 或 "trc20"),返回 30 分钟内有效的精确金额。最低 0.1 USDT。
第二步:校验收件人
POST /api/v1/check-username 会校验收件人并返回短时有效的验证令牌,防止向不存在的用户名付款;客户输错时,你能在扣款前得知。
第三步:获取并锁定价格
POST /api/v1/usd/quote 返回当前价格(usd)和加价比例(markup_percent: 5)。价格随市场变化,因此每次下单前都要获取新报价,在订单中传入等于报价的 max_usd,并始终发送 currency: "USD",否则将使用账户保存的偏好设置。
第四步:创建订单
POST /api/v1/stars/buy 或 /api/v1/premium/buy。每个请求必须带 Idempotency-Key:网络中断后重试也不会重复扣款。请把该键与订单 ID 一起存入数据库。
第五步:跟踪状态
GET /api/v1/order/{id} 和 /api/v1/orders 返回状态和历史。大多数订单几分钟内交付,完成后获得 TxId,你和客户都可以在 PayStars 公开账本中核验。
正确处理错误
- 409 price_changed:价格超过 max_usd,未扣款。重新报价并向客户展示新价格;
- 超出限速:不要超过每秒 10 次请求,加入队列或退避;
- 重试:始终使用同一个 Idempotency-Key。
上线前
把 API 密钥放在服务器环境变量而非代码中;用 50 Stars 的小额真实订单跑通全流程;向客户展示 TxId 以增强信任。完整文档见 PayStars Stars API 和 API 的 USD 定价;机器人内支付见 机器人中的数字商品只能用 Stars 支付。
常见问题
有沙盒环境吗?
没有单独的沙盒,集成时建议用小额真实订单(50 Stars)测试。
支持哪些编程语言?
任何能发送 HTTPS 请求的语言,并提供 Python、Node.js 和 PHP 快速入门。
如何为余额充值?
使用 TON、BEP20 或 TRC20 网络的 USDT,最低 0.1 USDT,每张账单金额精确、30 分钟内有效。
来源
用 USD(USDT)购买 Stars 和 Premium
API 密钥:0%(Fragment 原价)。网站:5%。
更多新闻
在乌兹别克斯坦购买 Telegram Stars 和 Premium:刷卡还是用 USDT在乌兹别克斯坦购买 Telegram Stars 或 Premium:@StarKerakBot 里的 Uzcard 和 Humo、paystars.uz/uz/ 上的 USDT、官方途径以及需要了解的当地规定。阅读 →
用 Telegram Stars 或 Premium 奖励比赛获胜者:主办方行动手册为自己举办的问答、比赛或黑客松获胜者发放 Telegram Stars 或 Premium:预算、收集 @username、通过 PayStars 发放以及结果公示。阅读 →
PayStars 常见问题:登录、USDT 充值、Stars 和 Premium 订单一页汇总 PayStars 最常见的问题:用 Telegram 登录、USDT(TON、BEP20 或 TRC20)充值、订购 Stars 和 Premium、交付时间、安全与 API。阅读 →