术语与概念
先把名词认全，后面读接口会顺很多。这一页只解释"是什么、为什么这么设计"， 具体字段去看对应的接口页。
核心概念
| 概念 | 英文 / 字段 | 是什么 | 为什么重要 |
|---|---|---|---|
| 商户号 | merchantNo | 你在平台上的对外的公开编号 | 收银台链接、扫码入口都用它。它是公开标识，不是凭证，泄漏了最多让人看到收款名称 |
| API KEY | apiKey（请求头 X-Pay-Api-Key） | 你的服务端调用开放接口的凭证 | 它同时是回调签名的密钥。泄漏等于别人能伪造"你的订单已付款"，所以只放在服务端、只存哈希 |
| 商户订单号 | merchantOrderNo | 你自己系统里的订单号 | 它是幂等键。重试必须用同一个号，平台靠它保证不会重复开单 |
| 平台订单号 | orderNo | 平台生成的订单编号 | 也是上链识别码的来源。它对买家也是公开的（收银页靠"知道订单号"查单） |
| 收款地址 | payAddress | 这笔钱该转到哪个地址 | 下单时锁定快照。你后来换地址不影响已创建的订单 |
| 收银台 | cashier | 买家看到的付款页面 | 分两种入口：固定收款台（/pay/cashier/m/{merchantNo}）与按订单进入的收银页 |
| 开放接口 | Open API | 服务端到服务端的接口，前缀 /api/pay/open/ | 调用方是你的服务端，身份只来自 API KEY，请求里不接受任何身份参数 |
| 链 | chainId / chainKey | 用哪条区块链网络收款 | chainKey 是代码里用的短名（如 tron、bsc），chainId 是平台内编号 |
| 代币 | tokenId / tokenSymbol | 这条链上收哪种币 | 每条链可能有多个代币，精度由代币决定，金额换算全靠它 |
| 精度 | decimals | 代币的最小单位位数 | USDT 常见为 6，但别的代币可能是 18。差一个精度就是差 10 的幂 |
| 最小单位 | *Minimal | 用整数表示的最小单位金额 | 避免浮点误差。回调与查询里的金额都是最小单位整数字符串 |
| 识别信息 | identify | 让平台把链上那笔钱匹配到这一单的标记 | 扫块时凭它区分"同地址的两笔同额转账"。原样透传，别改 |
| 回调 | notifyUrl | 平台通知你订单结果的地址 | 它是"我通知你"，会失败会被漏，所以还有查询接口 |
| 验签 | X-Pay-Signature | 回调真伪的校验值 | HMAC-SHA256，密钥是你的 API KEY，报文是时间戳拼正文 |
订单状态
订单状态是有限状态机，不是按"付款程度"排的连续数值。请按名字比对，不要用 >= 判断。
| 值 | 名称 | 含义 |
|---|---|---|
| 1 | 待支付 | 订单已创建，还没在链上看到这笔钱 |
| 2 | 已提交 | 链上已看到交易，确认数还不够 |
| 3 | 已确认 | 确认数达标。这是唯一会触发回调商家的状态 |
| 4 | 已完成 | 回调成功，订单走到终态 |
| 5 | 已过期 | 超过有效期仍未收到有效付款 |
| 6 | 待人工认领 | 链上有一笔钱分不清属于哪张单，需要人工指定，系统不猜 |
别用大小比较判断"付没付"
状态数值不是按付款程度递增的：已过期(5) 与 待人工认领(6) 的数值比 已确认(3) 大， 含义却与"付了钱"无关。判断"已付款"请只认 3 与 4。
订单类型
| 值 | 名称 | 说明 |
|---|---|---|
| 1 | 线上（SDK） | 由你的服务端通过开放接口创建，带你的 merchantOrderNo |
| 2 | 线下扫码 | 买家在收银页自己输金额创建，商户订单号由系统生成 |
这个字段决定要不要回调商家 —— 线上单才回调。别用"商户订单号是否为空"去判断， 因为这个字段两种单都有值。
开放接口的信任模型
开放接口与买家侧公开接口是两条完全不同的信任线，这是最容易搞混的地方：
开放接口 /api/pay/open/* | 买家侧公开接口 /api/pay/* | |
|---|---|---|
| 谁在调 | 你的服务端 | 任何打开收银页的人（买家没有账号） |
| 身份从哪来 | 请求头 X-Pay-Api-Key | "知道什么"（商户号、平台订单号） |
| 请求里能否传身份 | 不接受，就算传了也没有入口能读到 | 不接受商户 ID，商户由商户号解析 |
| 返回字段 | 你的完整字段（含实收金额、你的订单号） | 逐字段裁剪过的公开字段 |
| 中间件顺序 | 按 IP 兜底限流 → API KEY 认证 → 按商户限流 | 按 IP 兜底限流（写接口再加按商户一道） |
前两段限流的意义：认证之前没有商户身份，只能按 IP 挡"拿脚本刷 KEY"的洪水； 认证之后按商户再挡一道，因为一个商家可以换一批 IP 集中刷，而受害的是它自己的订单表。
部署形态：商家侧与平台侧分离
平台把"平台级配置"和"商户级配置"分开放：
- 平台侧管理链与代币、费率与规则、允许哪些商户用哪些链、平台的对外域名等。
- 商户侧只管理自己的收款地址、凭证、订单与报表。
两端独立部署。商户在商户后台看得见自己的经营数据，看不见平台配置； 平台侧对商户的收款地址只读 —— 改地址的动作一律由商户自己做， 这样"是谁把地址换掉的"才有据可查。
几个"还没有"的东西
尚未开放
以下能力在 MVP 阶段还没有上线，文档里不会给出对应的 URL，请通过官网注册入口或邮箱联系我们办理：
- 商家自助注册与注册邮箱验证码 —— 目前开通商户由平台人工受理。
- 免登录进入商户后台 —— 商户后台仍需账号密码登录。
- 匿名在线客服 —— 目前通过邮箱与既有渠道沟通。