开发者上手 · TgPay Crypto API

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

操作步骤

打开更多 → 商户 API，选择创建应用。
填一个应用名称（比如“我的小店”），并可选填一个 Webhook URL（选填）。
在表单中接受条款，再点创建应用。如有提示，请用 PIN 码或生物识别确认。创建应用即表示接受商户 API 使用条款——API 能用来做什么、不能用来做什么。
立刻把 API 令牌复制下来。 它只显示这一次，再也不会显示——服务器只存储令牌的散列值。
把令牌放进 TgPayCrypto-API-Token 请求头，发出您的第一个请求。

第一个调用

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

读取类方法使用 GET。写入类方法，如 createInvoice、transfer、createCheck、deleteInvoice 和 deleteCheck，只支持 POST。参数可通过 JSON 请求体、form-urlencoded 或查询参数传入。建议使用请求体，避免金额和幂等键出现在 URL 访问日志中。

测试网

建议先在测试网完成集成：API 和 Mini App 与主网相同，但测试币没有实际价值。

	主网	测试网
机器人	@tgpaycryptobot	@tgpaycrypto_testnet_bot
API 根地址	`https://app.tgpaycrypto.com/pay/api`	`https://testnet.tgpaycrypto.com/pay/api`
MCP 服务器	`https://app.tgpaycrypto.com/mcp`	`https://testnet.tgpaycrypto.com/mcp`

应用和令牌各自独立：测试网令牌无法在主网使用，反之亦然。要领取测试币，请打开测试网的 Mini App，在首页点领取测试币。测试币会像普通充值一样入账，已停用网络上的资产会跳过。应用会显示入账内容和下次可领取的时间。您可以用另一个 Telegram 账号充当支付测试账单的顾客。

充值和提现使用模拟托管，不会产生真实链上交易。绝不要向测试网充值地址发送真实资金。两套环境共用 API 协议，但可用功能、汇率和限额可能不同。做完之后，在 @tgpaycryptobot 里创建一个正式应用，把根地址换掉就行。

管理应用

在商户 API 中打开应用，即可查看应用 ID 和余额，并进行以下操作：

在 Webhook 中设置或更改 webhook URL，然后保存。
勾选额外的 webhook 事件——设好 webhook URL 之后，额外的 webhook 事件这几个开关让您按需订阅 invoice_paid 之外的事件类型（见 webhook 参考）。
限定 API 能打给谁——在付款设置中，新应用的通过 API 打款默认为任何用户；把它切到仅限名单内用户 （并把收款人列进名单），如果您的集成从来不用给人打款，就切到关闭——这是令牌万一泄露时的一道防线（见打款模式）。
创建受限令牌——打开权限与令牌，在受限令牌下签发额外的 API 令牌，每个令牌仅具有您选择的权限范围（见 API 参考）。
更换令牌——在权限与令牌中签发新令牌，同时立即作废旧令牌。令牌泄露时请使用此功能；新令牌同样只显示一次，跟创建时一样。
删除——请先转出可用余额，否则会返回 app_has_balance 并拒绝删除。删除前还应处理未领取完的红包和待领取打款。应用会从列表中移除，其令牌失效，付款记录则会保留。

Webhook

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

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

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

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

配置 webhook URL 后，invoice_paid 无需另行订阅。其他事件类型——账单过期、红包被领、退款、订阅相关事件——要通过 额外的 webhook 事件开关订阅。完整清单、payload 结构和重试策略都在 webhook 参考里。

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

它能授权从您应用余额转出资金。请把它留在服务器上，绝不要放进手机应用、前端产物或提交进仓库的配置文件。拿不准是不是泄露了，就换一个——更换是即时的，也不收费。另外，给每台服务器分配所需权限：只有 invoices 权限的受限令牌可以创建和删除账单，但不能转账、创建红包或退款。