Telegram 机器人收款：账单、Webhook 与打款
商户 API 是 TgPay Crypto 为机器人和服务提供的支付接口。创建应用、获取令牌，即可用代码创建账单，并接收带签名的付款 Webhook。兼容的 MCP 智能体也可协助接入。钱包余额付款在服务内部结算；链上付款需要达到所选网络的确认次数。
API 地址：app.tgpaycrypto.com/pay/api · 测试网：testnet.tgpaycrypto.com
从令牌到第一笔收款，只需四步
流程与常见支付 API 一样：创建账单、展示链接、接收事件。
创建应用
打开“更多 → 商户 API”，填写名称和 Webhook 地址。令牌仅显示一次，请妥善保存在服务器端。
创建账单
发送一次 createInvoice POST 请求，填写加密货币或法币金额、说明和截止时间，响应中即包含付款链接。
向用户展示链接
用户通过机器人中的按钮或链接，用钱包余额付款；大额付款需通过 PIN 码或 Face ID 确认。
处理 Webhook
服务器会收到以 HMAC-SHA256 签名的 invoice_paid 事件。验证签名、按 update_id 去重后，再交付商品。
接入工作，也可交给 AI 智能体
商户 API 提供 MCP 服务器。将其连接到兼容的 AI 智能体客户端后，AI 智能体可阅读文档、请求创建应用、配置 Webhook 并协助编写接入代码。您在 Telegram 中批准应用，并检查和测试结果。
- 步骤 1
把提示词发给 AI 智能体
请使用为您的账号或工作区提供远程 MCP 支持的 AI 智能体客户端。应用内“更多 → 商户 API → 接入 AI 智能体”也提供提示词。
- 步骤 2
在 Telegram 中确认应用授权
AI 智能体会提供一个 t.me 链接。机器人会列出申请内容，您点按按钮即可确认。链接仅可使用一次，确认前不会创建应用。
- 步骤 3
完成接入并测试
AI 智能体会获得受限令牌，并协助配置账单、订阅方案和 Webhook。如需获取 Webhook 签名密钥，请在应用中重新生成主令牌，并将其安全地保存在您的服务器上。
默认的 AI 智能体令牌可收款和配置 Webhook，不含转账、创建红包或退款权限。资金支出仍需由您授予相应权限。
AI 智能体接入流程，见开发文档Connect the MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the 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
在支持远程 MCP 的 AI 智能体客户端中连接 app.tgpaycrypto.com/mcp。经您在 Telegram 中批准后，AI 智能体可创建应用并协助接入。使用前请检查并测试结果。
兼容 Crypto Bot API
提供熟悉的方法名、{ok, result} 响应结构和 HMAC Webhook 签名。更换 API 地址和令牌后，请测试接入中使用的方法。
管理令牌权限
可限制令牌权限、立即更换令牌，将打款模式设为“仅限名单内用户”或“关闭”，并设置每日打款上限，降低令牌泄露带来的风险。
API 常见问题
了解令牌、Webhook 签名、测试和 API 迁移。
是否需要先完成身份验证，取决于当前政策。如果创建时提示验证错误，请在应用内完成验证后重试。
TgPayCrypto-API-Signature 请求头包含请求体的 HMAC-SHA256 签名，签名密钥为主令牌的 SHA-256。请对原始请求体字节进行验证；验证通过前，不要交付商品或将账单标为已付。
商户 API 提供熟悉的方法名、{ok, result} 响应结构、十进制字符串金额及 HMAC 签名。请更换 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 描述和分步指南。