开发者上手

在 Mini App 里创建一个应用，把它的 API 令牌复制下来（只有这一次机会），然后就能开始调 API 了。整套设置都在更多 → 商户 API里。

操作步骤

1. 打开更多 → 商户 API。
2. 填一个应用名称（比如“我的小店”），并可选填一个 Webhook URL。
3. 点创建应用。
4. 立刻把 API 令牌复制下来。 它只显示这一次，再也不会显示——应用那边只存它的散列值。
5. 把令牌放进 TgCryptoPay-API-Token 请求头，发出您的第一个请求。

第一个调用

把客户端指向 API 根地址 https://crypto.tgpaybot.com/pay/api，调 getMe 确认令牌能用。 getBalance 返回您应用的各项余额，getCurrencies 返回您能用的币种。

读取类方法是 GET。涉及资金的方法——createInvoice、transfer、createCheck 以及它们对应的 删除方法——是只收 POST 的，这是故意的：金额和幂等键不该出现在访问日志里。参数可以用 JSON body、form-urlencoded 或 query 参数传。

管理一个应用

商户 API 里每张应用卡片上都写着它的应用 ID 和余额，并且让您：

• 设置或更改 webhook URL，然后保存。
• 勾选额外的 webhook 事件——设好 webhook URL 之后，额外的 webhook 事件这几个开关 让您按需订阅 invoice_paid 之外的事件类型（见 webhook 参考）。
• 创建受限令牌——在受限令牌下面签发额外的 API 令牌，每一个都只带您挑的那些权限范围 （见 API 参考）。
• 更换令牌——签发一个新令牌，同时立刻作废旧的。令牌泄露了就用它；新令牌同样只显示 一次，跟创建时一样。
• 删除——这个应用不再能通过鉴权，但它的余额和付款记录都保留着。删除应用绝不会让它的资金 消失。

Webhook

您设了 webhook URL 的话，应用会往那儿 POST 一段带签名的 JSON：

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

签名在 TgCryptoPay-API-Signature 请求头里（Crypto-Pay-API-Signature 是兼容别名）： 对原始 body 做 HMAC-SHA256，密钥是您 API 令牌的 SHA-256。在信任 payload 里的任何 内容之前，请先验签。

投递会以指数退避在较长时间内重试，重试期间 update_id 保持不变——请拿它做去重，并且把您的 处理逻辑写成幂等的。

invoice_paid 一定会投递。其他事件类型——账单过期、红包被领、退款、订阅相关事件——要通过 额外的 webhook 事件开关订阅。完整清单、payload 结构和重试策略都在 webhook 参考里。

⚠️ 像对待私钥一样看好令牌

它能授权从您应用余额转出资金。请把它留在服务器上，绝不要放进手机应用、前端产物或提交进 仓库的配置文件。拿不准是不是泄露了，就换一个——更换是即时的，也不收费。另外，给每台服务器 只配它需要的：一个没有 payouts 权限的受限令牌能开账单，但永远动不了您的余额。