商户 API 参考
本页介绍各方法共用的调用规则，以及只读的目录类方法。各类方法的详细说明见： 账单和退款、转账和红包、 订阅、webhook。
本文所述方法遵循 Crypto Bot 的调用约定。请更换基础地址和令牌，再在测试网验证集成所用的方法。新增功能在下文标为扩展。
也提供机器可读的 OpenAPI 3.1 规范：crypto-pay-openapi.yaml · crypto-pay-openapi.json。可供代码生成器、API 客户端或 AI 工具使用，但请同时查阅各方法页面，因为规范可能尚未包含较新的扩展。
基础地址和鉴权
所有方法都在 https://app.tgpaycrypto.com/pay/api/<methodName>。在测试网上，
基础地址是 https://testnet.tgpaycrypto.com/pay/api，应用和令牌与主网分开，测试币没有实际价值。
每个请求都需在 TgPayCrypto-API-Token 请求头中提供令牌。为兼容旧集成，也接受 2026-09-07 之前使用的
TgCryptoPay-API-Token 和 Crypto-Pay-API-Token；同时发送多个时，以 TgPayCrypto-API-Token 为准。
令牌缺失、无效、已吊销，受限令牌已过期，所属应用已删除或所有者已被封禁时，返回 401 unauthorized。
令牌的形式是 <app_id>:<secret>，在创建或更换时显示一次；服务器只存它的散列值。见
开发者上手。
令牌和权限范围
两种凭据的鉴权方式完全一样：
- 主令牌——对每一个方法都有完整权限，也是唯一用于 webhook 签名的令牌。
- 受限令牌（扩展）——每个应用最多可有 10 个未吊销的令牌，包括已经过期的令牌。打开更多 → 商户 API，选择应用，再进入权限与令牌。在受限令牌下创建令牌，并为其设置标签和权限范围。吊销立即生效，不影响其他令牌；更换主令牌也不会影响受限令牌。令牌还可设置到期时间，到期后便无法用于鉴权。
| 权限范围 | 它开放的方法 |
|---|---|
| （任意有效令牌） | getMe、getCurrencies、getExchangeRates |
read | getBalance、getStats、getInvoices、getChecks、getTransfers、getSubscriptionPlans、getSubscriptions |
invoices | createInvoice、deleteInvoice |
refunds | refundInvoice |
payouts | transfer、transferBatch |
checks | createCheck、deleteCheck |
subscriptions | createSubscriptionPlan、archiveSubscriptionPlan、cancelSubscription |
webhooks | updateApp |
权限范围彼此独立，可组合使用。invoices 不包含 read，因此只负责创建账单的服务器可以使用无权读取余额和付款记录的令牌。调用超出令牌权限的方法会返回 403 scope_required。
getMe 返回当前令牌的 scopes（主令牌为 null）和 token_name，便于核对权限。
打款模式
权限范围决定令牌可调用哪些方法；应用的打款模式决定哪些人可以收到付款，对主令牌和受限令牌均适用。新应用默认可向任何用户打款。所有者可在更多 → 商户 API中打开应用，然后进入付款设置 → 通过 API 打款收紧限制。与每日限额一样，这项设置可限制令牌泄露后的影响。放宽限制需要 PIN 码或生物识别确认；API 只能读取该设置（getMe → payout_mode）。
payout_mode | transfer、transferBatch 和 createCheck 能做什么 |
|---|---|
any | 打给任何用户，给一个未知的 @username 暂存一笔打款，开谁都能领的红包——这是默认值，也是 Crypto Bot 的行为 |
allowlist | 仅向名单内的 Telegram 用户打款。红包的每位指定收款人或收款名单成员也都须在名单内。其他收款人、未知 @username 和不指定收款人的红包均返回 403 recipient_not_allowed |
off | 什么都不能做——每一次打款调用都返回 403 payouts_disabled；账单、订阅、退款和 webhook 照常工作 |
某笔打款被拒时，所有者会在 Telegram 里收到通知，并且可以改模式。除了模式， 每日打款限额也同样适用。打款可以用于什么，由 商户 API 使用条款规定。
请求和响应
- 读取类方法使用
GET，通过查询参数传值。涉及资金的方法只支持POST，参数可通过 JSON 请求体、form-urlencoded 或查询参数传入；发生冲突时以请求体为准。不接受multipart/form-data。 - API 处理程序生成的响应使用统一的 JSON 外层结构：成功为
{"ok": true, "result": …}，出错为{"ok": false, "error": {"code": <HTTP status>, "name": "<error_name>"}}。 请根据error.name判断错误类型；该字段是稳定的、机器可读的错误标识。 - GET 方法的查询参数类型错误时（如
offset=abc），请求可能在进入 API 处理程序前就被拒绝。请检查 HTTP 状态码，不要假定所有错误响应都使用上述结构，并按预期类型传入查询参数。
金额
- 加密货币金额是整币单位的小数字符串（
"10.5"）——绝不是 JSON 数字。响应里还带着amount_minor（扩展）：以字符串表示的最小单位整数值，因为 wei 量级的整数会超出 JavaScriptNumber的精确整数范围。 - 各币种的小数位数
decimals由getCurrencies提供。请据此计算金额，不要写死。 - 法币金额最多 2 位小数。
- 汇率是定点小数字符串，绝不是数字。
分页
列表类方法（getInvoices、getChecks、getTransfers、getSubscriptions）接受 offset
（默认 0）和 count（默认 100，最大 1000；getSubscriptions 最大 500），返回
{"items": […]}，按时间倒序。ID 过滤参数（invoice_ids、check_ids、transfer_ids）
是逗号分隔的整数列表。所有时间戳都是 ISO 8601 字符串。
幂等：spend_id
涉及资金的方法接受一个由调用方生成的 spend_id 键（1–64 个字符）：transfer 和
transferBatch 的每一项都必须给，createCheck 和 refundInvoice 可给可不给
（扩展，建议始终传入）。使用同一个键和相同参数重试，会返回原请求的结果，不会重复转出资金，因此超时后可以按原参数安全重试。同一个键配不同的参数会返回 409 idempotency_conflict；
原来那次还在执行时重试会返回 409 idempotency_in_progress。
频率限制
频率限制按应用计算，所有令牌共用额度。超出后返回 429 rate_limited：
| 方法 | 限制 |
|---|---|
createInvoice、createCheck | 每分钟 60 |
refundInvoice | 每分钟 30 |
transfer | 每分钟 30 |
transferBatch | 每分钟 10 |
updateApp | 每分钟 10 次 |
createSubscriptionPlan | 每分钟 20 次 |
还可能有其他请求限制。遇到 429 rate_limited 时，请延长重试间隔。平台维护期间，写入类方法返回 503 maintenance，读取照常。
目录和账户类方法
getMe
GET /pay/api/getMe——无参数。返回这个应用的身份信息：app_id、name、
payment_processing_bot_username、webhook_url、webhook_events（该应用订阅了的扩展
webhook 类型）、上面说过的令牌自省字段 scopes / token_name，以及
payout_mode（off / allowlist / any）、daily_payout_max_usd_cents（0 表示所有者未设置限额）和 daily_payout_spent_usd_cents（过去 24 小时内的支出）。
updateApp
POST /pay/api/updateApp——权限范围 webhooks。可选参数：name（1–64 个字符）、webhook_url（公网 HTTPS URL；空字符串表示移除），以及 webhook_events（受支持的扩展事件名数组或逗号分隔列表）。事件列表为空时，只保留 invoice_paid。返回字段与 getMe 相同。
getBalance
GET /pay/api/getBalance——无参数。每个支持的币种返回一行，余额为零也返回：
currency_code、available（可用余额）、onhold（未领取红包及待领取 @username 打款的资金），以及
amount_minor。
getCurrencies
GET /pay/api/getCurrencies——无参数。API 支持什么，以这份清单为准：加密货币行
（is_blockchain: true）和账单可以用来标价的法币（is_fiat: true）。每一行都带 code、
name、decimals 和 is_stablecoin 标记。
getExchangeRates
GET /pay/api/getExchangeRates——无参数。加密货币兑法币的报价：source、target、
rate（定点小数字符串）和 is_valid。这些汇率仅供参考。is_valid: true 不保证报价仍是最新的。无法获取汇率时，可能返回空数组。核对实际付款时，请使用账单记录的金额和汇率。
getStats
GET /pay/api/getStats——可选的 start_at / end_at（ISO 8601；默认窗口是最近 24 小时）。
返回 volume（窗口内完成付款的账单按当前汇率估算的美元价值；无报价的资产按零计算）、conversion（已付/已开，百分比）、
unique_users_count、created_invoice_count、paid_invoice_count，以及实际生效的窗口
边界。日期无法解析时返回 400 invalid_date。
每个方法都可能返回的错误
| HTTP | error.name | 原因 |
|---|---|---|
| 401 | unauthorized | 令牌缺失、无效或已吊销 |
| 403 | scope_required | 令牌没有这个方法要的权限范围 |
| 403 | payouts_disabled | 应用的打款模式是 off（仅打款方法） |
| 403 | recipient_not_allowed | 收款人不在应用的收款人名单上（仅打款方法） |
| 400 | invalid_request | 参数无法解析或无效（POST） |
| 403 | daily_cap_exceeded | 将超过应用每日打款限额 |
| 403 | verification_required | 所有者的转出操作受限，影响转账、红包和退款 |
| 503 | merchant_payouts_paused | 应用余额转出暂时停用 |
| 429 | rate_limited | 超过频率限制 |
| 503 | maintenance | 平台维护中（写入类方法） |
| 500 | internal_error | 服务器意外出错 |
各方法特有的错误列在各自的页面上。
非 JSON 格式的错误
仅凭纯文本或 HTML 错误响应，无法确定错误来自哪一层。请检查 HTTP 状态、响应正文和响应头。
如果 Cloudflare 返回 error code: 1010，说明它在请求到达 API 之前，根据浏览器特征拒绝了客户端。此 Cloudflare 错误并非由令牌权限引起。缺失或不常见的 User-Agent 可能触发网络保护。请尝试发送能标识您客户端的 User-Agent 请求头，例如 MyShop/1.0，然后重试；这并不保证能解决问题。如果错误仍然存在，请先移除令牌和 Cookie，再向支持团队提供 HTTP 状态、响应正文和响应头。
这篇文章对您有帮助吗？
谢谢反馈。