文档概述

• 接口总数：4个

认证与安全

约定前置参数

1. SM3 salt：双方预先约定的盐值
2. SM4 key：双方预先约定的加密密钥
3. 供应商侧测试及生产环境的ip/域名和接口地址
4. 行方回调通知接口地址

加密与签名规则

1. 业务数据加密：所有业务参数JSON字符串使用SM4算法加密，得到encryptedData字段
2. 签名生成规则：将毫秒级时间戳timestamp字符串与encryptedData字符串直接拼接，使用SM3算法结合预先约定的SM3 salt进行加密，最终输出十六进制字符串作为sign值
3. 签名示例代码：

import cn.hutool.crypto.SmUtil;
String sign = SmUtil.sm3WithSalt(sm3Salt.getBytes()).digestHex(timestamp+ encryptedData);

4. 所有接口请求头必须携带timestamp和sign两个参数，请求体为encryptedData加密字符串，Content-Type统一为application/json

接口列表

接口 1：卡券/直充权益下单接口

• 路径：双方约定的供应商下单接口地址
• 方法：POST
• 描述：适用于卡密，直充商品下单

请求参数

参数名	类型	必填	说明
请求头参数	-	-	-
timestamp	String	是	毫秒级时间戳
sign	String	是	签名，见签名规则
请求体参数	-	-	-
encryptedData	String	是	json格式业务数据进行SM4加密后的字符串
加密后业务参数（解密后）	-	-	-
actCode	String	是	活动code，可约定为各供应商的项目编号和密钥的拼接加密字符串
goodsCode	String	是	供应商商品编号
actOrderNum	String	是	活动方订单号，唯一，行内活动订单号
account	String	否	充值账号
callbackUrl	String	否	回调地址

响应参数

参数名	类型	说明
code	int	返回状态编码，0成功 -1失败
msg	String	返回错误信息
data	Object	JSON格式业务数据进行SM4加密后的字符串
解密后data业务参数	-	-
orderNo	String	权益订单号，唯一，供应商订单号
couponNo	String	卡号，卡券/短链类商品返回
couponCode	String	卡密，卡券类商品返回
status	Integer	状态，-1发放中 0成功 1失败 2已核销 3已过期
expireTime	String	有效期，卡券/短链类商品返回，格式：yyyy-MM-dd HH:mm:SS

示例

• 加密前业务请求示例：

{
  "actCode": "ACT001",
  "goodsCode": "123456",
  "actOrderNum": "00001",
  "account": "19912345678",
  "callbackUrl": "https://xxx/notice"
}

• 解密后响应示例：

{
  "code": 0,
  "msg": "请求成功",
  "data": "{\"orderNo\":\"HM17575805323790000127073398f3772c00\",\"expireTime\":\"2025-09-12 00:00:00\",\"couponNo\":\"27073398f3772c00\",\"couponCode\":\"27073398f3772c00\",\"status\":1}"
}

接口 2：卡券/直充/微信立减金订单查询接口

• 路径：双方约定的供应商查询接口地址
• 方法：POST
• 描述：行内通过供应商订单号查询订单状态接口

请求参数

参数名	类型	必填	说明
请求头参数	-	-	-
timestamp	String	是	毫秒级时间戳
sign	String	是	签名，见签名规则
请求体参数	-	-	-
encryptedData	String	是	json格式业务数据进行SM4加密后的字符串
加密后业务参数（解密后）	-	-	-
actCode	String	是	活动code，可约定为各供应商的项目编号和密钥的拼接加密字符串
orderNo	String	是	供应商订单号

响应参数

参数名	类型	说明
code	int	返回状态编码，0成功 -1失败
msg	String	返回错误信息
data	Object	JSON格式业务数据进行SM4加密后的字符串
解密后data业务参数	-	-
orderNo	String	权益订单号，唯一，供应商订单号
status	Integer	订单状态，-1发放中 0成功 1失败 2已核销 3已过期
account	String	充值账号，直充类型时存在
cardInfo	Object	卡券信息，卡券/短链类型时存在
-couponNo	String	卡号/短链
-couponCode	String	卡密
-expireTime	String	过期时间，格式：yyyy-MM-dd HH:mm:ss
couponId	String	优惠id，微信立减金类型时存在

示例

• 加密前业务请求示例：

{
    "actCode": "FBG6vdYqGE4mGX7EH/woEg==",
    "orderNo": "HM1757046717684000102707339840b23222"
}

• 解密后响应示例：

{
  "code": 0,
  "msg": "请求成功",
  "data": "{\"orderNo\":\"HM1757046717684000102707339840b23222\",\"cardInfo\":\"{\\\"couponNo\\\":\\\"11111\\\",\\\"couponCode\\\":\\\"12334\\\",\\\"expireTime\\\":\\\"2029-03-09 00:00:00\\\"}\",\"status\":3}"
}

接口 3：微信立减金订单充值接口

• 路径：双方约定的微信立减金充值接口地址
• 方法：POST
• 描述：微信立减金订单充值

请求参数

参数名	类型	必填	说明
请求头参数	-	-	-
timestamp	String	是	毫秒级时间戳
sign	String	是	签名，见签名规则
请求体参数	-	-	-
encryptedData	String	是	json格式业务数据进行SM4加密后的字符串
加密后业务参数（解密后）	-	-	-
actCode	String	是	活动code，可约定为各供应商的项目编号和密钥的拼接加密字符串
orderNo	String	是	供应商订单号
goodsCode	String	是	供应商商品编号
actOrderNum	String	是	活动方订单号，唯一，行内订单号
appId	String	是	公众账号ID
openId	String	是	微信用户标识，需要与 appId 绑定（同一个 appId 下的 openId）
callbackUrl	String	否	回调地址

响应参数

参数名	类型	说明
code	int	返回状态编码，0成功 -1失败
msg	String	返回错误信息
data	Object	json格式业务数据进行SM4加密后的字符串
解密后data业务参数	-	-
orderNo	String	权益订单号，唯一，供应商订单号
status	Integer	订单状态，-1发放中 0成功 1失败 2已核销 3已过期
couponId	String	微信优惠id，微信该批次立减金的优惠id

示例

• 加密前业务请求示例：

{
  "actCode": "FBG6vdYqGE4mGX7EH/woEg==",
  "goodsCode": "0001",
  "actOrderNum": "0001",
  "openId": "0001",
  "appId": "00001"
}

• 解密后响应示例： 成功响应：

{
  "code": 0,
  "msg": "请求成功",
  "data": "{\"orderNo\":\"0001\",\"couponId\":\"123456\",\"status\":1}"
}

失败响应：

{
  "code": -1,
  "msg": "库存不足",
  "data": null
}

接口 4：卡券/直充/微信立减金充值结果通知接口

• 路径：行方提供的回调地址
• 方法：POST
• 描述：供应商主动推送充值结果通知给行方

请求参数

参数名	类型	必填	说明
请求头参数	-	-	-
timestamp	String	是	毫秒级时间戳
sign	String	是	签名，见签名规则
请求体参数	-	-	-
encryptedData	String	是	json格式业务数据进行SM4加密后的字符串
加密后业务参数（解密后）	-	-	-
orderNo	String	是	供应商订单号，唯一
actOrderNum	String	是	活动方订单号，唯一，行内订单号
status	Integer	是	订单状态，-1发放中 0成功 1失败 2已核销 3已过期
account	String	否	直充账号，直充类型商品时存在
cardInfo	Object	否	卡券信息，卡券/短链类型商品时存在
-couponNo	String	是	卡号/短链，卡券/短链类型商品时存在
-couponCode	String	是	卡密，卡券类型商品时存在
-expireTime	String	是	卡券过期时间，卡券/短链类型商品时存在
couponId	String	否	微信优惠id，微信立减金类型商品时存在

响应参数

参数名	类型	说明
HTTP状态码200	String	返回内容为ok，代表接收成功，系统认为回调已处理成功，不会重试
HTTP状态码非200	任意内容	系统认为接收失败，将按重试策略重试，最多3次

示例

• 加密前回调业务参数示例：

{
  "orderNo":"HM202509291010001",
  "actOrderNum":"XY2025092910100001",
  "status":3,
  "account":"19912345678"
}

错误码

错误码	说明	处理建议
0	请求成功	正常处理返回数据
-1	请求失败	读取msg字段获取具体失败原因，例如库存不足等

回调通知

回调机制说明：

1. 供应商在订单状态发生变更时，主动调用行方提供的回调通知接口推送最新订单状态
2. 回调请求同样遵循SM4加密、SM3签名的安全规则
3. 行方收到回调后，校验签名、解密数据处理完成后，必须返回HTTP 200状态码且响应内容为ok，否则供应商侧会进行重试，最多重试3次