需要双方约定的参数：
- SM3 sallt
- SM4 key
- 供应商侧测试及生产环境的ip/域名和接口地址
- 行方回调通知接口地址
签名规则：
timestamp+ encryptedData 字符串拼接后通过sm3盐值加密
签名示例：
import cn.hutool.crypto.Smutil;
String sign = SmUtil.sm3WithSalt(sm3Salt.getBytes()).digestHex(timestamp+ encryptedData);
一、卡券/直充权益下单接口
|
|
| 接口名称 |
卡券/直充权益下单接口 |
| 接口描述 |
适用于卡密，直充商品下单 |
| 接口环境 |
测试： 生产： |
| 接口地址 |
|
| 请求方式 |
POST |
| 报文格式 |
content-type：application/json |
入参说明
|
|
|
|
|
| 通用请求参数 |
必填 |
类型 |
描述 |
取值说明 |
| 请求头 |
|
|
|
|
| timestamp |
是 |
String |
时间戳 |
毫秒级时间戳 |
| sign |
是 |
String |
签名 |
见签名规则 |
| 请求体 |
|
|
|
|
| encryptedData |
是 |
String |
加密数据 |
json格式业务数据进行SM4加密 |
|
|
|
|
|
| 业务数据参数 |
必填 |
类型 |
描述 |
取值说明 |
| actCode |
是 |
String |
活动code |
可约定为各供应商的项目编号和密钥的拼接加密字符串 |
| goodsCode |
是 |
String |
商品code |
供应商商品编号 |
| actOrderNum |
是 |
String |
活动方订单号 |
唯一，行内活动订单号 |
| account |
否 |
String |
充值账号 |
|
| callbackUrl |
否 |
String |
回调地址 |
|
示例：原始业务参数（加密前）
|
| { "actCode": "ACT001", "goodsCode": "123456", "actOrderNum": "00001", "account": "19912345678", "callbackUrl": "https://xxx/notice" } |
响应消息
|
|
|
|
|
| 公共响应参数 |
必填 |
类型 |
描述 |
说明 |
| code |
是 |
int |
返回状态编码 |
0成功 -1失败 |
| msg |
是 |
String |
返回错误信息 |
|
| data |
否 |
Object |
返回数据 |
JSON格式业务数据进行SM4加密 |
|
|
|
|
|
| 响应参数名称 |
必填 |
类型 |
描述 |
说明 |
| orderNo |
是 |
String |
权益订单号 |
唯一，供应商订单号 |
| couponNo |
否 |
String |
卡号 |
卡券/短链类商品返回 |
| couponCode |
否 |
String |
卡密 |
卡券类商品返回 |
| status |
是 |
Integer |
状态 |
-1发放中 0成功 1失败 2已核销 3已过期 |
| expireTime |
否 |
String |
有效期 |
有效期，卡券/短链类商品返回 格式：yyyy-MM-dd HH:mm:SS |
示例：响应消息内容（解密后）
|
| { "code": 0, "msg": "请求成功", "data": "{"orderNo":"HM17575805323790000127073398f3772c00","expireTime":"2025-09-12 00:00:00","couponNo":"27073398f3772c00","couponCode":"27073398f3772c00","status":1}" } |
二、卡券/直充/微信立减金订单查询接口
|
|
| 接口名称 |
卡券/直充/微信立减金订单查询接口 |
| 接口描述 |
行内通过供应商订单号查询订单状态接口 |
| 接口环境 |
测试： 生产： |
| 接口地址 |
|
| 请求方式 |
POST |
| 报文格式 |
content-type：application/json |
入参说明
|
|
|
|
|
| 通用请求参数 |
必填 |
类型 |
描述 |
取值说明 |
| 请求头 |
|
|
|
|
| timestamp |
是 |
String |
时间戳 |
毫秒级时间戳 |
| sign |
是 |
String |
签名 |
见签名规则 |
| 请求体 |
|
|
|
|
| encryptedData |
是 |
String |
加密数据 |
json格式业务数据进行SM4加密 |
|
|
|
|
|
| 业务数据参数 |
必填 |
类型 |
描述 |
取值说明 |
| actCode |
是 |
String |
活动code |
可约定为各供应商的项目编号和密钥的拼接加密字符串 |
| orderNo |
是 |
String |
供应商订单号 |
|
示例：原始业务参数（加密前）
|
| { "actCode": "FBG6vdYqGE4mGX7EH/woEg==", "orderNo": "HM1757046717684000102707339840b23222" } |
响应消息
|
|
|
|
|
| 公共响应参数 |
必填 |
类型 |
描述 |
说明 |
| code |
是 |
int |
返回状态编码 |
0成功 -1失败 |
| msg |
是 |
String |
返回错误信息 |
|
| data |
否 |
Object |
返回数据 |
JSON格式业务数据进行SM4加密 |
|
|
|
|
|
| 响应参数名称 |
必填 |
类型 |
描述 |
说明 |
| 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 |
微信立减金类型时存在 |
示例：响应消息内容（解密后）
|
| { "code": 0, "msg": "请求成功", "data": "{"orderNo":"HM1757046717684000102707339840b23222","cardInfo":"{\"couponNo\":\"11111\",\"couponCode\":\"12334\",\"expireTime\":\"2029-03-09 00:00:00\"}","status":3}" } |
三、微信立减金订单充值接口
|
|
| 接口名称 |
微信立减金订单充值接口 |
| 接口环境 |
测试： 生产： |
| 接口地址 |
|
| 请求方式 |
POST |
| 报文格式 |
content-type：application/json |
入参说明
|
|
|
|
|
| 通用请求参数 |
必填 |
类型 |
描述 |
取值说明 |
| 请求头 |
|
|
|
|
| timestamp |
是 |
String |
时间戳 |
毫秒级时间戳 |
| sign |
是 |
String |
签名 |
见签名规则 |
| 请求体 |
|
|
|
|
| encryptedData |
是 |
String |
加密数据 |
json格式业务数据进行SM4加密 |
|
|
|
|
|
| 业务数据参数 |
必填 |
类型 |
描述 |
取值说明 |
| actCode |
是 |
String |
活动code |
可约定为各供应商的项目编号和密钥的拼接加密字符串 |
| orderNo |
是 |
String |
供应商订单号 |
|
| goodsCode |
是 |
String |
商品code |
供应商商品编号 |
| actOrderNum |
是 |
String |
活动方订单号 |
唯一，行内订单号 |
| appId |
是 |
String |
公众账号ID |
|
| openId |
是 |
String |
微信用户标识 |
需要与 appId 绑定（同一个 appId 下的 openId） |
| callbackUrl |
否 |
String |
回调地址 |
|
示例：原始业务参数（加密前）
|
| { "actCode": "FBG6vdYqGE4mGX7EH/woEg==", "goodsCode": "0001", "actOrderNum": "0001", "openId": "0001", "appId": "00001" } |
响应消息
|
|
|
|
|
| 公共响应参数 |
必填 |
类型 |
描述 |
说明 |
| code |
是 |
int |
返回状态编码 |
0成功 -1失败 |
| msg |
是 |
String |
返回错误信息 |
|
| data |
否 |
Object |
返回数据 |
json格式业务数据进行SM4加密 |
|
|
|
|
|
| 响应参数名称 |
必填 |
类型 |
描述 |
说明 |
| orderNo |
是 |
String |
权益订单号 |
唯一，供应商订单号 |
| status |
是 |
Integer |
订单状态 |
-1发放中 0成功 1失败 2已核销 3已过期 |
| couponId |
是 |
String |
微信优惠id |
微信该批次立减金的优惠id |
示例：响应消息内容（解密后）
|
| { "code": 0, "msg": "请求成功", "data": "{"orderNo":"0001",,"couponId":"123456","status":1}" } { "code": -1, "msg": "库存不足", "data": null } |
四、卡券/直充/微信立减金充值结果通知接口
|
|
| 接口名称 |
卡券/直充/微信立减金充值结果通知接口 |
| 接口路径 |
行内提供回调地址 |
| 请求方式 |
POST |
| 报文格式 |
content-type： application/json |
入参说明
|
|
|
|
|
| 通用请求参数 |
必填 |
类型 |
描述 |
取值说明 |
| 请求头 |
|
|
|
|
| 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 |
微信立减金类型商品时存在 |
示例：原始业务参数（加密前）
|
| { "orderNo":"HM202509291010001", "actOrderNum":"XY2025092910100001", "status":3, "account":"19912345678" } |
响应消息
|
|
|
| 状态码 |
返回内容 |
说明 |
| 200 |
ok |
接收成功，系统认为回调已处理成功，不会重试 |
| 其它 |
任意内容 |
系统认为接收失败，将按重试策略重试，最多3次 |
注：接受到结果后判断HTTP状态码，返回ok 认为接收成功，否则会尝试回调3次。