Telegram 机器人收款：账单、Webhook 与打款
商户 API 是 TG Crypto Pay 为机器人和服务提供的支付接口。在机器人中创建应用、获取令牌，即可用代码创建账单，并在付款后接收带签名的 Webhook。也可把 MCP 服务器地址交给 AI 智能体完成接入。付款在钱包内部结算，无网络手续费，无需等待网络确认。
API 地址：app.tgpaycrypto.com/pay/api · 测试网：testnet.tgpaycrypto.com
从令牌到第一笔收款，只需四步
流程与常见支付 API 一样：创建账单、展示链接、接收事件。
创建应用
打开“更多 → 商户 API”，填写名称和 Webhook 地址。令牌仅显示一次，请妥善保存在服务器端。
创建账单
发送一次 createInvoice POST 请求，填写加密货币或法币金额、说明和截止时间，响应中即包含付款链接。
向用户展示链接
在您的机器人中放置按钮或链接，用户即可使用钱包余额付款。
处理 Webhook
服务器会收到以 HMAC-SHA256 签名的 invoice_paid 事件。验证签名、按 update_id 去重后，再交付商品。
接入工作，也可交给 AI 智能体
商户 API 提供 MCP 服务器。把地址交给 AI 智能体，它即可阅读文档、创建应用、配置 Webhook 并编写代码。无需打开终端或手动复制令牌。
- 步骤 1
把提示词发给 AI 智能体
可使用 Claude Code、claude.ai、Claude Desktop、ChatGPT 或其他 MCP 客户端。应用内“更多 → 商户 API → 接入 AI 智能体”也提供相同提示词。
- 步骤 2
在 Telegram 中确认应用授权
AI 智能体会提供一个 t.me 链接。机器人会列出申请内容，您点按按钮即可确认。链接仅可使用一次，确认前不会创建应用。
- 步骤 3
AI 智能体完成后续配置
它会取得受限令牌，完成账单、订阅方案和 Webhook 接入。Webhook 签名密钥仍由您在应用内保管。
默认的 AI 智能体令牌可收款和配置 Webhook，不含转账、创建红包或退款权限。资金支出仍需由您授予相应权限。
AI 智能体接入流程，见开发文档Connect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
在客户端设置中添加自定义 MCP 连接器，地址填入 app.tgpaycrypto.com/mcp
https://testnet.tgpaycrypto.com/mcp
手续费与限额
这些数值取自本页生成时应用公开的限额目录，最新数值以应用内显示为准。
商户 API 能做什么
应用有独立于个人钱包的余额：账单收款计入应用余额，打款和创建红包从中支出。
账单与退款
可设固定加密货币金额、法币计价金额，或让付款人自行填写金额。支持全额或部分退款，也适用于匿名付款。
订阅
用户首次授权订阅方案后，每个周期自动扣款，每次扣款均有事件通知。
转账与红包
从应用余额向 Telegram 用户打款，或创建可供领取的红包链接。
Webhook
invoice_paid 始终发送。账单过期、红包领取、退款和订阅事件可按应用自行启用。
测试网
@tgpaycrypto_testnet_bot 提供相同的 API 和小程序。首页按钮每小时可领取一次测试币。
AI 智能体与 MCP
把 app.tgpaycrypto.com/mcp 交给您的 AI 智能体，它即可创建应用、配置 Webhook 并编写接入代码。您只需在机器人中确认应用授权。
兼容 Crypto Bot API
沿用相同的方法名、{ok, result} 响应结构和 Webhook 签名方式。更换 API 地址和令牌，即可沿用原代码。
管理令牌权限
可限制令牌权限、立即更换令牌，将打款模式设为“仅限名单内用户”或“关闭”，并设置每日打款上限，降低令牌泄露带来的风险。
API 常见问题
了解令牌、Webhook 签名、测试和 API 迁移。
是否需要先完成身份验证，取决于当前政策。如果创建时提示验证错误，请在应用内完成验证后重试。
TgPayCrypto-API-Signature 请求头包含请求体的 HMAC-SHA256 签名，签名密钥为主令牌的 SHA-256。请对原始请求体字节进行验证；验证通过前，不要交付商品或将账单标为已付。
不需要。商户 API 沿用 Crypto Bot API 的方法、{ok, result} 响应结构、十进制字符串金额及签名方式。更换 API 地址和令牌即可，原 Crypto-Pay-API-Token 请求头仍可作为别名使用。
测试网提供相同的 API 和小程序：机器人为 @tgpaycrypto_testnet_bot，API 地址为 testnet.tgpaycrypto.com/pay/api。首页“领取测试币”按钮每小时可领取 1,000 USDT、1,000 GRAM 和 0.01 BTC。主网与测试网令牌不能混用。
默认获取的受限令牌可创建账单和订阅方案、查询余额与统计、设置 Webhook 地址。转账、红包和退款需要相应打款权限；普通接入令牌不包含这些权限。
商户 API 公开文档
docs.tgpaycrypto.com 提供接口说明、OpenAPI 描述和分步指南。