加密货币支付网关 API：接入前必查的 12 项要点
每个加密货币支付 API 都能创建账单，差异体现在重试、部分付款和 Webhook 失败时。这是一份写给开发者的 12 项检查清单，并说明 mistKET API 如何应对每一项。
每个加密货币支付网关 API 承诺的都是同一件事：创建账单、收到付款、接收回调。差异往往在后面才暴露——两个请求同时到达时、客户少付了一点时、你的服务器宕机一小时时，或者攻击者重放截获的请求时。认真挑选 API 节省的时间，远多于快速接入省下的时间。
这是一份写给开发者和 CTO 的清单，供你在动手写代码之前比较各家加密货币支付 API。每一项都说明要看什么、为什么重要，以及 mistKET API 如何处理。如果你已经选好、想看分步代码，请直接阅读我们的加密货币支付 API 接入指南。
最基本的端点
一个可用的加密货币支付 API 不能只有“创建付款”。至少应具备：
| 功能 | 为什么需要 | mistKET 端点 |
|---|---|---|
| 创建账单 | 每笔订单一个付款请求，带有效期 | POST /invoices |
| 查询账单 | Webhook 丢失时进行对账 | GET /invoices/{uuid} |
| 列出和筛选账单 | 后台视图和每晚对账 | GET /invoices |
| 取消账单 | 订单被放弃时释放库存 | POST /invoices/{uuid}/cancel |
| 支持的资产 | 只显示当前可以付款的网络 | GET /assets |
| 汇率报价 | 创建账单前显示加密货币金额 | GET /rate |
| 健康检查 | 监控和优雅降级 | GET /health |
如果服务商无法查询或列出账单，你就只能盲目信任 Webhook——第一次投递失败时就会陷入被动。
1. 认证：每个请求都签名了吗？
在请求头里直接发送 API Key 是最弱的方式：任何截获或泄露它的人都能创建和取消账单。应优先选择用从不在网络上传输的密钥为每个请求签名的 API。mistKET 的请求携带 X-Api-Key、X-Api-Timestamp，以及对时间戳和原始请求体计算的 HMAC-SHA256 签名。密钥在商户后台只显示一次。
2. 防重放
仅有签名并不能阻止别人重发截获的请求。要看是否有时间戳窗口和 nonce 支持。mistKET 拒绝与服务器时间相差超过 ±300 秒的时间戳，并且对改变状态的请求拒绝重复使用同一签名。签名第 2 版为每个请求加入 nonce，并同时对请求方法和路径签名，因此签名无法挪到其他端点上使用。
3. 创建账单的幂等性
网络会超时。如果你的收银流程重试“创建账单”调用，一笔订单绝不能出现两张账单。好的 API 会提供幂等键。在 mistKET 中，你自己的 order_id 就起这个作用：用相同订单号再次调用，会返回已存在的账单并带上 "idempotent": true，而不会新建一张。
4. 覆盖真实付款情况的状态模型
“已付 / 未付”远远不够。客户可能因为交易所扣了手续费而少付一点，也可能多付，或者在过期后才付款。确认 API 会明确呈现这些情况。mistKET 账单的状态包括 new、pending、underpaid、paid、confirmed、overpaid、expired 和 cancelled，并提供 paid_amount、remaining_amount、can_pay_remaining 和 under_review 等字段，让你的代码无需猜测。
paid 表示已检测到转账、正在等待确认；只有在 confirmed 或 overpaid 时才发货。5. 可见的确认数
API 应告诉你一笔付款已有多少个区块确认、需要多少个，并提供交易哈希和区块浏览器链接。这样付款相关的客服工单就能快速查清。mistKET 为每张账单返回 confirmations、required_confirmations 以及 transactions[] 数组，包含哈希、金额、状态和浏览器链接。
6. 汇率锁定与计价货币
你用法币定价，客户用加密货币付款。要问清支持哪些法币、报价汇率保持多久。mistKET 支持以 USD、EUR、TRY、RUB、GBP 和 AED 计价（也可直接用加密货币符号计价），在账单有效期内锁定汇率，并允许为每张账单设置 5 到 1440 分钟的有效期。
7. 网络选择
能否在 API 调用中固定网络，或让客户在托管页面上自行选择？两者都有用：固定网络适合机器人和自动化流程，让客户选择则能减少转错网络。mistKET 通过 pay_currency + network 或 asset_id 同时支持两种方式；当某个网络没有空闲地址时，GET /assets 会返回 available: false。目前已启用 TRON（TRC-20）上的 USDT；其他资产和网络可按商户申请开通。为什么 TRON 是常见的默认选择，请看 USDT TRC20 与 ERC20 对比。
8. 签名、可重试、可追踪的 Webhook
大多数集成都坏在 Webhook 上。检查四点：载荷有签名；有时间戳可拒绝过期投递；失败的投递会持续重试数小时（而不是几秒）；每次投递都有可用于去重的 ID。mistKET 使用独立的 Webhook Secret 签名，发送 X-Mistket-Delivery 和 X-Mistket-Event 请求头，对非 2xx 响应在 10 秒、30 秒、2 分钟、10 分钟、30 分钟、1 小时、2 小时和 3 小时后重试，投递历史可在后台查看。我们的加密货币支付 Webhook 一文深入讲解处理程序设计。
9. 有文档的错误与速率限制
你应该事先知道签名错误、IP 被封或校验失败时会返回什么。mistKET 返回统一的 { "success": false, "error": … } 响应体，校验错误会附带逐字段详情，使用标准状态码（401、403、404、422、429、503），并公开限额：每个 API Key 每分钟 120 次请求。
10. 网络层面的控制
有了 IP 白名单，泄露的密钥离开你的服务器就毫无用处。mistKET 允许你在后台设置白名单；来自其他地址的请求会收到 403。再加上请求签名和较短的时间戳窗口，最常见的攻击路径基本都被堵住了。
11. 不被 SDK 绑定
SDK 很方便，直到它跟不上你的语言版本。基于纯 HTTPS 和 JSON、签名只需一次 HMAC 调用的 API，可以在 PHP、Node.js、Python、Go 或 Shell 脚本中使用。mistKET 在 API 文档中提供可直接复制的 PHP、Node.js 和 Python 客户端，但都不是必需的。
12. 给非开发人员的手动方式
即使是以 API 为核心的企业，也需要给个别客户开一次性账单。确认账单也能在后台创建并以链接分享，这样销售和客服就不必找开发人员。在 mistKET 中，同样的账单可以在商户后台使用，每个托管收银页都可以作为付款链接。
GET /invoices/{uuid} 进行比对。一次就能验证签名、Webhook 处理程序和对账逻辑。评估加密货币支付 API 时的危险信号
- Webhook 没有签名，或仅靠一个秘密 URL 来“保护”。
- 创建后无法查询账单。
- 没有 underpaid 或 overpaid 状态——边缘情况最后都涌进客服聊天。
- 只重试几分钟，或者没有投递日志。
- 速率限制和错误格式没有文档。
- 单笔交易费用不透明——可对照我们的加密货币支付网关费用指南。
如何获取 mistKET API 权限
商户由 mistKET 团队审核接入：在 Telegram 上联系 @mistnetwork，提供你的网站、业务类型和预计交易量。审核通过后，你可以在商户后台创建 API Key、Secret 和 Webhook 设置。一般一个下午就能完成接入。
