开发文档

Telegram Bot 收款:Stars、订单与退款

按数字商品与实体商品选择收款流程,核验 successful_payment,再履约并保留退款所需的付款标识。

GetTGAPI 编辑团队更新于
文档解读核对日期

依据官方资料整理,由 GetTGAPI 独立维护。 文档目录与术语表 →

本页内容
  1. 先明确商品类型
  2. 付款确认后才履约
  3. 订单设计建议
  4. 测试边界

先明确商品类型

Telegram 内的数字商品和服务使用 Stars,币种为 XTR;实体商品和服务使用相应支付服务商流程。用户购买 Stars 的价格可能受渠道及税费影响,不能直接等同于商家可提取的收益。

普通货币金额按官方币种数据中的精度处理,不是所有货币都固定乘以 100。

付款确认后才履约

发送发票后,先处理 pre_checkout_query,再等待 successful_payment。预结算通过不是到账证据。保存 telegram_payment_charge_id,它用于关联付款与后续退款。Stars 数字商品不需要实体支付的 provider token。

订单设计建议

建立独立订单号,将 Bot、用户、商品、币种及金额绑定。处理支付更新时核验这些字段,并通过唯一付款标识实现重复事件幂等。付款成功但业务失败时进入可追踪的补偿或退款状态,不能再次要求用户付款来修复程序错误。

测试边界

官方提供 Stars 测试环境;本地模拟只能验证代码分支,不能替代真实环境的收款与退款验收。为用户保留支付问题入口,并能从付款记录定位到具体履约结果。