接口概览
接口风格
- RESTful 风格，接口命名 kebab-case（如
pay-order而非payOrder） - 基于 HTTP 协议，请求与响应均为
JSON格式
API 架构
DaxPay 对外提供开放支付 API：
| 层级 | 路径前缀 | 认证方式 | 响应类 | 用途 |
|---|---|---|---|---|
| 支付 API | /unipay/* | RSA 签名验签 | DaxResult | 服务器对服务器调用（下单、支付、退款、查询、关闭等） |
面向对象
支付 API 面向商户后端系统，通过 RSA 签名认证，无需登录态。商户端 Web 面板使用的内部管理接口不在本文档范围内。
支付 API 的三类接口
/unipay/* 下按业务场景细分为三类：
| 类别 | 路径前缀 | 场景 | 文档 |
|---|---|---|---|
| 直连支付 | /unipay/pay、/unipay/close、/unipay/refund、/unipay/query/*、/unipay/sync/* | 商户后端已确定通道与支付方式 | 统一支付 · 申请退款 |
| 网关支付 | /unipay/gateway/* | 由平台收银台/聚合页选择支付方式 | 网关预下单 |
| 分账 | /unipay/alloc、/unipay/query/alloc-order、/unipay/sync/order/alloc | 对分账订单发起分账、查询与同步 | 发起分账 |
| 退款查询 | /unipay/query/refund-order | 按退款单号精确查询单笔退款 | 查询退款单 |
探活与自检
平台提供两个探针接口，用于在联调初期区分「网络不通」和「配置不对」：
| 端点 | 请求 | 鉴权 | 回答的问题 |
|---|---|---|---|
/unipay/callback/ping | GET | 免签名 | 服务是否可达——返回固定标识文本，无任何副作用；与通道回调同一前缀，能访问即代表通道回调链路在网络层已通 |
/unipay/ping | POST | 需签名 | 签名配置是否正确——走与业务接口完全相同的验签链路（商户身份 → 验签 → 防重放），通过后回显命中的应用信息，响应带平台签名，可顺带验证平台公钥配置 |
POST /unipay/ping 请求体只需 mchNo 与签名字段（appId 可省略，省略时回落默认应用）。建议在发起第一笔真实业务请求前先调用它：能通，说明商户号、应用、私钥、待签名串构造全链路正确，之后的业务报错基本只剩业务原因。
WARNING
签名探针会消耗防重放 nonce 槽位，用于联调自检即可，请勿当作高频健康检查。
基础地址
http://{系统域名}:{端口}示例：https://your-domain.com（生产环境），本地开发默认端口 9999。
对接流程
- 注册商户：在管理平台注册商户，获取商户号（mchNo）和应用 ID（appId）。
- 配置密钥：生成 RSA 密钥对，将商户公钥注册到平台；平台分配平台公钥用于验签响应。
- 接口调用：按本文档定义的规范构造请求（含签名），发起支付、查询、关闭等请求。
- 接收回调：配置异步通知地址（
notifyUrl），接收支付/退款结果通知。
通用请求头
| 参数名 | 必填 | 描述 |
|---|---|---|
| Content-Type | 是 | application/json，所有请求均为 JSON 格式 |
签名机制
支付 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-01 20:00:00",
"reqId": "REQ20241201001"
}| 字段 | 类型 | 描述 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| msg | string | 提示信息 |
| data | object | 业务数据 |
| sign | string | 平台对响应的 RSA 签名，商户可验签 |
| resTime | string | 响应时间（北京时间，yyyy-MM-dd HH:mm:ss） |
| reqId | string | 请求 ID（回显入参 reqId） |
注意字段名
支付 API 响应字段为 msg（非 message）。
通用约定
请求方式
支付 API 交易接口均为 POST 方式请求，请求体为 JSON 格式；个别认证接口为 GET（如 获取用户标识）。
日期格式
支付 API（/unipay/**）的全部时间字段（请求、响应、异步通知）统一使用北京时间格式 yyyy-MM-dd HH:mm:ss，不带时区后缀：
json
{ "reqTime": "2024-12-01 12:00:00" }- 平台签名时使用的时间字面量与报文完全一致，商户务必用同一字面量参与签名（见签名机制）；
- 请求时间字段请勿使用 ISO 8601（如
2024-12-01T04:00:00Z）或带亚秒精度的写法，与平台规范字面量不一致会导致验签失败（错误码20052）。
金额单位
所有金额字段类型为 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 | 交易号（一笔订单可多次尝试，每次生成新交易号） |