接口格式定义 - 星惠付开放平台

协议规则

项	约定
传输方式	接口域名：测试环境 `https://go-test.xft.xin` 生产环境 `https://gw.xft.xin` 接口路径统一以 `/openapi` 开头
提交方式	全部采用 POST + 固定路径，不使用路径参数；业务标识（`out_apply_no`、`merchant_code` 等）一律放在请求 body
数据格式	JSON，字符编码统一 UTF-8，`Content-Type: application/json`（图片上传为 `multipart/form-data`）
签名	app_key 对称签名（HMAC-SHA256），请求携带签名头，响应头恒带 `Signature`，见签名验签说明

公共参数

身份与签名通过 HTTP Header 传递，业务字段平铺在请求 body，无嵌套信封：

Header	说明	必填
`Content-Type`	`application/json`	是
`Client-Id`	渠道商/品牌 app_key（32 位十六进制），平台据此定位身份与密钥	是
`Signature-Type`	固定 `HmacSHA256`	是
`Timestamp`	请求时间，秒级时间戳（int64），与平台时间差不得超过 5 分钟	是
`Nonce-Str`	随机字符串（建议 32 位十六进制），同一 app_key 下 5 分钟内不可重复	是
`Signature`	请求签名，见签名验签说明	是

请求报文

POST /openapi/v1/merchant/apply/query
Host: gw.xft.xin
Content-Type: application/json
Client-Id: a1b2c3d4e5f67890a1b2c3d4e5f67890
Signature-Type: HmacSHA256
Timestamp: 1755234000
Nonce-Str: 9f8e7d6c5b4a39281706f5e4d3c2b1a0
Signature: 5b2f9c3d...

{
  "out_apply_no": "P20260815001"
}

响应报文

成功响应

HTTP 200，业务数据直接平铺在响应 body，无任何业务码包装，响应头恒带 Signature：

{
  "out_apply_no": "P20260815001",
  "apply_no": "AP2026081500001",
  "apply_status": "AUDITING",
  "timestamp": "2026-08-15 10:00:23"
}

失败响应

HTTP 4xx/5xx + 统一错误体：

{
  "code": 400,
  "reason": "PARAM_ERROR",
  "message": "参数错误,参数[merchant_code]",
  "metadata": {}
}

字段	说明
`code`	错误码数值（int32），取值见返回码说明；业务错误时与 HTTP 状态码一致
`reason`	错误码枚举（ErrorReason），机器可读，排查与重试判断以 `reason` 为准
`message`	可读描述，面向渠道商，不使用内部术语；参数类错误带出错字段名
`metadata`	附加定位信息，可为空

网关层拒绝是「code 与 HTTP 状态码一致」的例外：验签失败返回 HTTP 401，但 body 中 code 为 NO_AUTH（403）；Client-Id 对应的 app_key 无效返回 HTTP 400，body 同为 NO_AUTH（403）。详见签名验签说明。

商户录入重复提交（同一调用主体、同一 out_apply_no）属于幂等例外：不报错，返回 HTTP 200 与已受理申请单的当前状态。

公共约定

项	约定
时间	业务字段（如 `timestamp`）一律为字符串，格式 `yyyy-MM-dd HH:mm:ss`（北京时间）；签名头 `Timestamp` 为秒级时间戳
金额	一律为字符串，单位为分（如 `"100"` 表示 1 元）；费率 `val` 为十万分比（0.6% → `"600"`）
枚举	状态/类型类字段一律英文语义值（如 `AUDITING`、`FLAT`），不使用数字裸值
空值	空值字段省略，不返回也不上送
图片	`multipart/form-data` 上传（单张 ≤5MB），上传后 `key` 7 天有效，录入时以 `category` + `key` 引用
回调地址	`back_url` 必须为 HTTPS