Official TON Pay

富途学院

🐼 富途学院| TON × AI × Web3

频道入口：@futuxy

一句话流程

用户在小程序 / 机器人里下单 → 后端用 TON Pay 创建支付 → 用户用 Tonkeeper / Wallet 等钱包签名 → TON Pay 监听链上结果 → Webhook 通知你的服务器 → 自动发货。

老手看到这里基本就懂了：TON Pay 不是一个“收款地址生成器”，而是一套订单支付 + 链上确认 + 回调通知的收款基础设施。

为什么小程序和机器人需要 TON Pay？

很多 Telegram Mini App 和 Bot 迟早都会遇到一个问题：怎么让用户在 TON 上付款，并且付款后自动给权益？

比如：

AI Bot：用户充值 TON，获得对话次数 / 积分 / 会员。

工具类小程序：用户支付 TON，解锁高级功能。

付费社群：用户支付 TON，自动进入频道或群组。

游戏 / 抽奖 / Mini App：用户付费购买道具、门票、次数。

电商订单：用户用 TON 或 Jetton 支付，系统自动确认订单。

如果你只是贴一个钱包地址，让用户转账后发截图，那会有三个问题：

不好识别订单：几十个人同时付款，谁付的是哪一单？

不好自动发货：你要人工查交易哈希，效率很低。

容易出错：金额、备注、网络、地址，任何一步错了都麻烦。

TON Pay 解决的就是这件事：把链上付款变成一个可追踪的订单流程。

TON Pay 是什么？

根据 TON 官方文档，TON Pay SDK 是一套用于 TON 区块链支付集成的开发工具，支持 Web 应用、Telegram Mini Apps、后端服务和机器人。

它做三件核心工作：

创建支付：一次性转账、订阅、带 reference / memo 的订单付款。

追踪状态：监听交易确认、处理 pending / success / error。

通知业务系统：通过 Webhook 把支付结果发回你的后端。

支持的钱包也比较全：Tonkeeper、MyTonWallet、Tonhub、OpenMask、TON Wallet、Wallet bot 等，底层走 TON Connect。

最适合的产品形态

1）Telegram Mini App 收款

这是最顺的形态。用户在 Mini App 里点“支付”，前端展示 TON Pay Button，钱包弹出签名，支付完成后页面自动变成成功状态。

2）Telegram Bot 收款

Bot 本身不能替用户签名付款。正确做法是：Bot 创建订单，然后发一个按钮，把用户带到 Mini App / Web checkout 页面完成支付。支付成功后，后端再通知 Bot 给用户开权限。

3）AI Agent / 自动化服务

比如用户给 AI Bot 充值 5 TON，系统记录 reference，确认成功后给用户增加 500 次调用额度。这类场景最需要自动回调，不能靠人工查账。

开发者接入思路

前端负责“让用户签名付款”，后端负责“创建订单、保存 reference、确认结果、发货”。

最小流程可以拆成 5 步：

01：准备 TON Connect manifest，让钱包知道你的应用是谁。

02：前端接入 TonConnectUIProvider。

03：用 TON Pay 创建转账 message。

04：用户在钱包里确认并签名。

05：用 reference 查询状态，或通过 Webhook 接收支付完成通知。

前端怎么做？

官方推荐用 TON Pay 的 UI 组件，尤其是 React 项目里可以直接使用 TonPayButton。

它帮你处理这些麻烦事：

连接钱包

发起 TON Connect 交易

处理 loading 状态

处理用户取消 / 钱包断开 / 重复提交

把交易结果交给后续状态查询

也就是说，你不用自己从 0 写钱包连接和交易签名 UI。

后端一定要保存什么？

如果是机器人、小程序、电商订单，后端至少要保存这些字段：

user_id：Telegram 用户 ID 或你系统里的用户 ID。

order_id：你的业务订单号。

amount：应收金额。

asset：收 TON 还是 Jetton。

recipientAddr：你的收款钱包地址。

reference：TON Pay 返回的追踪 ID。

status：pending / success / error。

txHash：成功后保存链上交易哈希。

重点：不要只相信前端说“我付了”。必须以后端查询或 Webhook 的支付结果为准。

Webhook 才是自动发货的关键

TON Pay 支持 Webhook。支付在链上完成并被 TON Pay 索引后，会向你的服务器发送 POST 请求。

一个标准处理逻辑是：

收到 transfer.completed 事件。

验证请求签名。

检查 data.status 是 success 还是 failed。

按 reference 找到你的订单。

确认金额和资产无误。

更新订单状态，给用户发货 / 开通会员 / 增加积分。

返回 2xx，告诉 TON Pay 已收到。

Webhook 的好处是：用户付款后不用刷新页面，Bot 也不用人工查账，系统可以自动处理。

小程序 / Bot 的推荐架构

Bot 负责触达用户，Mini App 负责支付页面，后端负责订单和回调。

可以这样设计：

Bot：用户点击“充值”或“开会员”。

后端：创建订单，生成 order_id。

Mini App：展示套餐和 TON Pay Button。

钱包：用户确认签名并支付。

TON Pay：追踪链上状态。

Webhook：通知你的后端支付成功。

Bot：给用户发成功通知，发放权益。

4 个必须避开的坑

1）不要用“固定收款地址 + 截图”当正式支付系统。

这样无法稳定识别订单，也很难自动化。

2）不要只信前端回调。

用户点了钱包确认，不等于链上最终成功。要查 reference 状态，或者等 Webhook。

3）不要漏掉 reference。

reference 是订单和链上付款之间的桥。没保存 reference，后面很难追踪。

4）生产环境别忘了改 mainnet。

文档示例通常用 testnet。上线前要确认 chain、收款地址、API key、Webhook URL 全部是生产配置。

一句话总结

如果你的小程序、机器人、AI Bot 想收 TON，不要让用户截图转账。用 TON Pay：创建订单、钱包签名、链上确认、Webhook 自动发货。

这才是 Telegram 生态里更像“支付系统”的收款方式。

参考资料：TON Pay SDK overview、TON Pay Quick start、TON Pay Webhooks