接口概览
接口风格
- RESTful 风格，接口命名 kebab-case（如
pay-order而非payOrder） - 基于 HTTP 协议，请求与响应均为
JSON格式
两层 API 架构
DaxPay 对外提供两层 API，认证方式与响应格式不同：
| 层级 | 路径前缀 | 认证方式 | 响应类 | 用途 |
|---|---|---|---|---|
| 支付 API | /unipay/* | RSA 签名验签 | DaxResult | 服务器对服务器调用（下单、查询、关闭等） |
| 管理 API | /mch/* | Sa-Token 会话 | Result | 商户端 Web 面板操作（退款、列表、同步等） |
区分要点
支付 API 面向商户后端系统，通过 RSA 签名认证，无需登录态；管理 API 面向商户 Web 面板，通过 Accesstoken 请求头（Sa-Token）认证。
支付 API 的三类接口
/unipay/* 下按业务场景细分为三类：
| 类别 | 路径前缀 | 场景 | 文档 |
|---|---|---|---|
| 直连支付 | /unipay/pay、/unipay/close、/unipay/query/*、/unipay/sync/* | 商户后端已确定通道与支付方式 | 统一支付 |
| 网关支付 | /unipay/gateway/* | 由平台收银台/聚合页选择支付方式 | 网关预下单 |
| 通道认证 | /unipay/assist/channel/auth/* | 获取用户 openId/userId（OAuth 授权） | 获取授权链接 |
基础地址
http://{系统域名}:{端口}示例：https://your-domain.com（生产环境），本地开发默认端口 9999。
对接流程
- 注册商户：在管理平台注册商户，获取商户号（mchNo）和应用 ID（appId）。
- 配置密钥：生成 RSA 密钥对，将商户公钥注册到平台；平台分配平台公钥用于验签响应。
- 接口调用：按本文档定义的规范构造请求（含签名），发起支付、查询、关闭等请求。
- 接收回调：配置异步通知地址（
notifyUrl），接收支付/退款结果通知。
通用请求头
| 参数名 | 必填 | 描述 |
|---|---|---|
| Content-Type | 是 | application/json，所有请求均为 JSON 格式 |
| Accesstoken | 管理API必填 | Sa-Token 会话令牌（仅 /mch/* 管理接口需要；支付 API /unipay/* 不需要） |
签名机制
支付 API（/unipay/*）使用 RSA 签名认证，签名字段在请求体内（非请求头）：
| 字段 | 位置 | 描述 |
|---|---|---|
| sign | 请求体 | RSA 签名值（Base64 编码） |
| reqTime | 请求体 | 请求时间（yyyy-MM-dd HH:mm:ss，GMT+8） |
| reqId | 请求体 | 请求唯一标识，防重放 |
| nonceStr | 请求体 | 随机字符串，防重放 |
签名生成细节参见 签名机制。
通用响应体（支付 API）
DaxResult 结构：
json
{
"code": 0,
"msg": "success",
"data": {},
"sign": "Base64签名值",
"resTime": "2024-12-01T12:00:00Z",
"reqId": "REQ20241201001"
}| 字段 | 类型 | 描述 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| msg | string | 提示信息 |
| data | object | 业务数据 |
| sign | string | 平台对响应的 RSA 签名，商户可验签 |
| resTime | string | 响应时间（UTC，ISO 8601） |
| reqId | string | 请求 ID（回显入参 reqId） |
注意字段名
支付 API 响应字段为 msg（非 message）。管理 API（Result）使用 message。
通用约定
请求方式
支付 API 接口使用 POST 方式请求，请求体为 JSON 格式。管理 API 查询接口使用 GET，操作接口使用 POST。
日期格式
所有日期时间字段使用 OffsetDateTime，序列化为 ISO 8601 带 UTC 偏移：
- 请求/响应中的时间字段：
yyyy-MM-dd HH:mm:ss（GMT+8） - 响应中的 UTC 时间（如
resTime）：ISO 8601 格式
金额单位
所有金额字段类型为 Long，单位为分，避免浮点数精度丢失。 例如：1元 → 100
状态值
状态字段类型为 String（非数字），使用语义化的英文小写编码：
- 支付状态（
PayStatusEnum）：wait/progress/success/close/cancel/fail/timeout - 退款状态（
RefundOrderStatusEnum）：progress/success/fail/close - 退款标记（
PayRefundStatusEnum）：no_refund/refunding/partial_refund/refunded
术语表
| 术语 | 描述 |
|---|---|
| mchNo | 商户号（Merchant Number），唯一标识接入商户 |
| appId | 应用 ID，商户下创建的应用标识 |
| RSA 密钥对 | 商户生成 RSA 密钥对，公钥注册到平台，私钥用于签名请求 |
| method | 支付方式，如 wechat_qr、alipay_pc（见 PayMethodEnum） |
| product | 支付产品，如 alipay_pc、wechat_native（见 通道码表） |
| orderNo | 系统订单号 |
| bizOrderNo | 商户业务订单号 |
| tradeNo | 交易号（一笔订单可多次尝试，每次生成新交易号） |