协议说明
中合智付开放平台所有接口通过统一入口访问，采用 HTTPS POST 传输 JSON 数据，接口间通过 method 与 version 参数进行区分，具体业务参数以 JSON 字符串形式置于 bizContent 中。
统一网关入口
text
POST /gateway/v1- 测试环境：
https://test.harmopay.com/gateway/v1 - 生产环境：
https://openapi.harmopay.com/gateway/v1
公共请求参数
| 参数名 | 中文名 | 是否必选 | 数据类型 | 说明 |
|---|---|---|---|---|
| accessId | 应用访问 ID | 是 | String(32) | 开放平台分配的接入应用标识 |
| method | 接口方法名 | 是 | String(128) | 目标接口名称，如 ups.trade.transfer |
| version | 接口版本 | 是 | String(10) | 固定传入 V1 |
| timestamp | 请求时间戳 | 是 | String(19) | 格式 yyyy-MM-dd HH:mm:ss，与北京时间偏差不超过 ±5 分钟 |
| charSet | 字符编码 | 否 | String(10) | 编码格式，固定 utf8 |
| format | 报文格式 | 否 | String(10) | 数据交换格式，固定 json |
| signType | 签名算法 | 是 | String(10) | RSA2 或 SM2，由接入凭证密钥类型决定 |
| signData | 签名结果串 | 是 | String(344) | 请求签名值，Base64 编码，见签名与验签 |
| authToken | 授权令牌 | 否 | String(40) | 应用授权令牌，未使用时保持空值；参与签名时保留 authToken= 形式 |
| bizContent | 业务参数集合 | 是 | String | 业务参数 JSON 序列化字符串 |
公共响应参数
| 参数名 | 中文名 | 数据类型 | 说明 |
|---|---|---|---|
| resCode | 响应码 | String(6) | 000000 表示受理成功，其余均为失败 |
| resMsg | 响应描述 | String(128) | 平台返回的处理结果描述 |
| traceId | 链路追踪 ID | String(32) | 全链路唯一标识，排障时可提供给平台协助排查 |
| signType | 签名算法 | String(10) | 平台签名算法，与请求凭证一致 |
| signData | 平台签名串 | String(344) | 平台私钥对响应报文生成的 Base64 签名串，接入方应进行验签 |
| resContent | 业务响应数据 | String | 业务返回参数 JSON 序列化字符串，验签后反序列化获取具体业务字段 |
网关公共层返回码
以下错误码由开放平台网关层直接校验并返回：
| 错误码 | 错误描述 | 排查指引 |
|---|---|---|
900001 | 应用 ID 无效 | 检查 accessId 是否正确，对应应用是否已启用 |
900002 | 无效的服务请求 | 检查 method 是否正确，或该接口权限是否已开通 |
900003 | 服务不可用 | 目标服务正在维护中，请稍后重试 |
900004 | 网关请求错误 | HTTP 请求体格式非法，须为合法的 UTF-8 JSON 报文 |
900005 | 签名验证失败 | 签名计算错误或私钥不匹配，请核对公钥证书与待签串拼装格式 |
900006 | 网关请求超时 | 业务处理超时，请调用对应查询接口核实单据状态 |
900007 | 非法报文，不允许空请求体 | 检查 HTTP POST Body 是否为空 |
900008 | 网关响应签名错误 | 平台签名服务异常，请联系技术支持 |
900009 | 请求时间戳无效 | timestamp 与服务器时间偏差超过 5 分钟，请校准服务器 NTP 时钟 |
900010 | 请求重复（疑似重放攻击） | 短时间内检测到完全相同的请求报文，请勿重复提交 |
900011 | 无权限调用该接口 | 当前 accessId 未开通该 API 的调用权限 |
900012 | 请求过于频繁 | 触发接口限流保护，请降低调用频率后重试 |
900013 | 幂等请求冲突 | 相同业务单号的请求正在处理中，请稍后查询结果，勿重复发起 |
900014 | 接口版本无效 | version 需固定传入 V1 |
900015 | 开放平台访问凭证无效 | 请求未携带有效凭证，或测试/生产环境凭据混用 |
900016 | 访问凭证与目标商户不匹配 | 报文中的 merchantId 与 accessId 绑定的商户号不一致 |
各业务域的具体业务错误码见全局错误码表。
调用须知
- 请求报文大小：HTTP 请求体上限为 256KB；
- 时钟同步：请求时间戳容忍窗口为 ±5 分钟，请接入方服务器保持 NTP 时间同步；
- 超时重试原则：调用交易类接口发生超时或返回未知状态（如
999999）时，请先调用对应查询接口确认单据真实状态，避免盲目重复发起造成重复付款。详见幂等与防重放。