先明确商品类型
Telegram 内的数字商品和服务使用 Stars,币种为 XTR;实体商品和服务使用相应支付服务商流程。用户购买 Stars 的价格可能受渠道及税费影响,不能直接等同于商家可提取的收益。
普通货币金额按官方币种数据中的精度处理,不是所有货币都固定乘以 100。
付款确认后才履约
发送发票后,先处理 pre_checkout_query,再等待 successful_payment。预结算通过不是到账证据。保存 telegram_payment_charge_id,它用于关联付款与后续退款。Stars 数字商品不需要实体支付的 provider token。
订单设计建议
建立独立订单号,将 Bot、用户、商品、币种及金额绑定。处理支付更新时核验这些字段,并通过唯一付款标识实现重复事件幂等。付款成功但业务失败时进入可追踪的补偿或退款状态,不能再次要求用户付款来修复程序错误。
测试边界
官方提供 Stars 测试环境;本地模拟只能验证代码分支,不能替代真实环境的收款与退款验收。为用户保留支付问题入口,并能从付款记录定位到具体履约结果。