指南 · PayStars

面向开发者的 PayStars API:在机器人中销售 Stars 和 Premium 的完整流程

以集成方案的形式讲解 PayStars REST API:X-API-Key、用户名校验、USD 报价与 max_usd、幂等订单、409 price_changed 错误以及 TxId 核验。

发布于: · 更新于:

面向开发者的 PayStars API:在机器人中销售 Stars 和 Premium 的完整流程

想在自己的机器人、商店或应用里销售 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%。

开始