合利宝通用收银台接口对接指南

接口概述

通用收银台：一个接口下单，返回链接用户自行选择支付方式。

| 接口 | 路径 | 说明 | |------|------|------| | 预支付 | /trx/universalcashier/unifiedorder | 下单，返回支付链接 | | 订单查询 | /trx/universalcashier/query | 查询订单状态 | | 订单退款 | /trx/universalcashier/refund | 发起退款 | | 退款查询 | /trx/universalcashier/refundQuery | 查询退款状态 | | 分账退款 | /trx/universalcashier/splitBillRefund | 分账订单退款 | | 银行卡查询 | /trx/universalcashier/queryUserBindCard | 查询用户绑卡 | | 银行卡解绑 | /trx/universalcashier/bankCardUnbind | 解除绑卡 | | 订单含退款查询 | /trx/universalcashier/queryFull | 查询订单及退款详情 |

支付方式：微信、支付宝、银联云闪付、快捷支付（需人脸识别）、网银支付。

---

接口地址

| 环境 | 地址 | |------|------| | 测试 | http://test.trx.helipay.com/trx/universalcashier/unifiedorder | | 生产 | https://trx.helipay.com/trx/universalcashier/unifiedorder |

---

请求方式

• 方法：POST
• 格式：application/x-www-form-urlencoded
• 加密：SM4 对称加密（data 域）
• 签名：MD5WITHRSA 或 SM3WITHSM2

统一请求参数：

| 字段 | 必填 | 说明 | |------|------|------| | data | 是 | SM4 加密后的订单数据（JSON 串） | | customerNumber | 是 | 商户号 | | encryptionKey | 是 | SM4 key 使用平台公钥 SM2 加密后的结果 | | signType | 否 | MD5WITHRSA 或 SM3WITHSM2 | | sign | 是 | 签名结果 | | timestamp | 是 | 13 位毫秒时间戳 | | version | 否 | 默认 1.0 |

---

返回响应

{
  "code": "0000",
  "message": "成功",
  "data": "{\"wapUrl\":\"https://...\",\"prepayId\":\"...\"}",
  "sign": "..."
}

验签规则：对 data 域进行验签。

---

与 helipay-sm2 技能配合

本技能负责接口字段组装和协议规范，实际加解密/签名/验签调用 helipay-sm2 技能。

1. 签名（请求前）

请求签名只对加密后的 data 字符串进行签名，不需要拼接其他参数，也不需要拼接秘钥。

调用 helipay-sm2：

输入：加密后的 data 字符串 + 商户私钥
输出：SM3WITHSM2 签名值

2. SM4 加密（请求前）

需要加密的内容：

• data 域：整个订单 JSON 串
• encryptionKey：SM4 key 使用平台公钥 SM2 加密

调用 helipay-sm2：

输入：data 明文 JSON + 随机生成的 SM4 key
输出：SM4 加密后的 data + SM2 加密后的 SM4 key

3. SM4 解密（收到响应后）

调用 helipay-sm2：

输入：加密的 data + 加密的 SM4 key（用商户私钥解密）
输出：解密后的 data 明文 JSON

4. 验签（收到响应后）

调用 helipay-sm2：

输入：data 明文 + 返回的 sign + 平台公钥
输出：验签是否通过

---

核心接口参数

预支付接口

data 域参数（SM4 加密前）：

| 字段 | 必填 | 说明 | |------|------|------| | orderId | 是 | 商户请求流水号（唯一） | | orderNo | 是 | 商户订单号 | | goodsName | 是 | 商品名称 | | orderAmount | 是 | 金额（单位：元） | | serverCallbackUrl | 是 | 异步通知地址 | | payerName | 快捷必选 | 用户姓名（人脸识别用） | | idCardNo | 快捷必选 | 身份证号（人脸识别用） | | userId | 否 | 用户 ID（用于绑卡支付） | | callbackUrl | 否 | 页面回跳地址 | | prepaymentMethod | 否 | 指定支付方式（WXPAY/ALIPAY/QUICKPAY） |

返回（解密后）：

• wapUrl：收银台 H5 地址（用户在此选择支付方式）
• prepayId：预支付标识
• orderNo：商户订单号

订单查询接口

data 域： | 字段 | 必填 | 说明 | |------|------|------| | orderId | 是 | 商户订单号 |

订单退款接口

data 域： | 字段 | 必填 | 说明 | |------|------|------| | orderId | 是 | 商户请求流水号（唯一） | | refundAmount | 是 | 退款金额（单位：元） | | refundOrderId | 是 | 商户退款订单号（唯一） | | serverCallbackUrl | 是 | 退款异步通知地址 |

退款查询接口

data 域：refundOrderId（商户退款订单号）

分账订单退款接口

data 域：orderId、refundAmount、ruleJson（分账规则串）、refundOrderId、serverCallbackUrl

银行卡查询接口

data 域：userId

银行卡解绑接口

data 域：userId、cardNo

订单含退款查询接口

data 域：orderId

---

签名规则详解

请求签名

仅对加密后的 data 字符串进行签名，不需要拼接其他参数，也不需要拼接秘钥。

待签名串 = 加密后的 data 字符串
sign = SM3WITHSM2(待签名串，商户私钥)

回调验签

合利宝异步通知回调参数：

• 参数按 ASCII 码升序排序
• 空值参数排除
• 不参与签名的字段：encryptionKey、sign、signatureType
• 拼接后直接 SM3WITHSM2 验签（不追加秘钥）

示例代码：

// 移除不参与签名的字段
signMap.remove("encryptionKey");
signMap.remove("signatureType");
signMap.remove("sign");
// 按 ASCII 排序并拼接
String signStr = mapToSignatureStr(signMap);
// 验签
boolean verified = SM3WITHSM2.verify(publicKey, signStr, sign);

---

代码示例（Java）

// 1. 组装订单数据
JSONObject data = new JSONObject();
data.put("orderId", "ORDER_20260525_001");  // 商户请求流水号
data.put("orderNo", "ORDER_20260525_001No"); // 商户订单号
data.put("goodsName", "测试商品");
data.put("orderAmount", 0.01); // 0.01 元，单位是元
data.put("serverCallbackUrl", "https://your-domain.com/callback");
// 快捷支付需额外传入：
// data.put("payerName", "张三");
// data.put("idCardNo", "110101199001011234");

// 2. SM4 加密 data、SM2 加密 SM4 key、对加密后的 data 签名 → 调用 helipay-sm2 技能完成

// 3. 发起 HTTP 请求
HttpPost post = new HttpPost(url);
List<NameValuePair> formParams = new ArrayList<>();
formParams.add(new BasicNameValuePair("data", encryptedData));
formParams.add(new BasicNameValuePair("customerNumber", merchantNo));
formParams.add(new BasicNameValuePair("encryptionKey", encryptedKey));
formParams.add(new BasicNameValuePair("signType", "SM3WITHSM2"));
formParams.add(new BasicNameValuePair("sign", sign));
formParams.add(new BasicNameValuePair("timestamp", timestamp));
formParams.add(new BasicNameValuePair("version", "1.0"));
post.setEntity(new UrlEncodedFormEntity(formParams, "UTF-8"));

// 4. 执行请求并处理响应
HttpResponse response = httpClient.execute(post);
String responseBody = EntityUtils.toString(response.getEntity(), "UTF-8");
JSONObject result = JSONObject.parseObject(responseBody);

// 5. 验签 + SM4 解密 data → 调用 helipay-sm2 技能完成
JSONObject dataObj = JSONObject.parseObject(decryptedData);
String wapUrl = dataObj.getString("wapUrl"); // 收银台 H5 地址
String prepayId = dataObj.getString("prepayId"); // 预支付标识

---

注意事项

• 金额单位：元
• 流水号唯一：orderId、refundOrderId 必须全局唯一
• 快捷支付：必须传入 payerName + idCardNo 用于人脸识别
• 回调地址：必须可外网访问，做好幂等处理
• 敏感信息：不在日志中明文记录身份证、卡号

---

完整流程

1. 组装订单 JSON（orderId、orderNo、goodsName、orderAmount 等） → SM4 加密 → 得到 data
2. 生成 SM4 key → 平台公钥 SM2 加密 → 得到 encryptionKey
3. 对加密后的 data 字符串签名 → helipay-sm2 签名 → 得到 sign
4. POST 请求到合利宝
5. 收到响应 → 验签 → SM4 解密 data → 获取 wapUrl
6. 用户打开 wapUrl 选择支付方式完成支付
7. 合利宝异步通知回调地址

---

生成时的说明要求

最终回答需要包含：

• 接口请求方式：POST form 表单（application/x-www-form-urlencoded），不是 JSON。
• 统一请求参数：data（SM4 加密）、customerNumber、encryptionKey（SM2 加密）、sign、signType、timestamp、version。
• 统一返回响应：code、message、data（SM4 加密）、sign、signType。
• 接口字段说明：预支付接口必填字段（orderId、goodsName、orderAmount、serverCallbackUrl），快捷支付必传 payerName+idCardNo 用于人脸识别。
• 签名规则：请求签名仅对加密后的 data 字符串进行签名，不需要拼接其他参数，也不需要拼接秘钥；回调验签参数按 ASCII 排序，空值排除，encryptionKey/sign/signatureType不参与签名，不拼接秘钥。
• SM4 加密：data 域 JSON 调用 helipay-sm2 进行 SM4 加密，SM4 key 调用 helipay-sm2 使用平台公钥进行 SM2 加密。
• 代码示例：请求组装、加密、签名、HTTP 调用的完整示例。
• 配合 helipay-sm2：签名、SM4 加密、SM4 解密、验签均调用 helipay-sm2 技能完成。
• 人脸识别：快捷支付必须传入 payerName 和 idCardNo。
• 依赖：JDK8+，Hutool 5.8.5 + BouncyCastle 1.76（与 helipay-sm2 一致）。
• 职责划分：本技能负责字段组装和协议规范，加解密/签名/验签由 helipay-sm2 完成。
• 金额单位：元（不是分）。