快捷协议查询接口
1.修订记录
修订 | 日期 | 说明 | 作者 |
---|---|---|---|
V0.1 | 2018/06/19 | 新接口参数定义 | 邓文泉 |
V0.2 | 2021/12/27 | 支持国密 | 王晶 |
V0.3 | 2022/03/31 | 新增响应参数行别 | 林竞 |
2.业务说明
(1)场景说明
1、用户签约成功后,通过该接口可以进行协议查询
(2)接口说明
1、快捷协议查询接口
3.请求地址
环境 | HTTPS请求地址 |
---|---|
正式环境 | https://trusteeship.ysepay.com/gateway.do |
4.参数说明
4.1公共请求参数
参数 | 类型(长度) | 必填 | 参数说明 |
---|---|---|---|
method | String(128) | Y | 接口名称 固定值 ysepay.trusteeship.fastPay.queryProtocol |
partner_id | String(20) | Y | 在银盛支付开设的服务商商户号,请联系客户经理提供 |
timestamp | String(19) | Y | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" 示例值:2014-07-24 03:07:50 |
charset | String(10) | Y | 商户网站使用的编码格式,如UTF-8、GBK、GB2312等,默认值 GBK |
sign_type | String(10) | Y | 报文签名算法,RSA/SM |
sign | String(256) | Y | 签名字符串,再用Base64编码 |
version | String(3) | Y | 接口版本3.0 当前版本 3.0 |
biz_content | String | Y | 业务请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递 |
4.2 业务请求参数
参数名biz_content,值为一个json格式对象,下面列表描述json对象的值
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
protocol_no | String(20) | Y | 银盛支付平台的签约流水号 示例值:K2018061401969840970 |
5.响应参数说明
银盛支付对商户的请求数据处理完成后,会将处理的结果数据同步回执给商户。
请注意:银盛后期会对返回参数保留扩展的权力,扩展方式为新增参数但不会删除参数,请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
5.1 公共响应参数
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
sign | String | Y | 签名字符串,Base64编码 |
ysepay_trusteeship_fastPay_queryProtocol_response | String | Y | 业务响应参数的集合,最大长度不限 |
5.2 业务响应参数
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
code | String | Y | 响应代码 |
msg | String | Y | 响应代码描述 |
trade_status | String(30) | Y | 签约目前所处的状态:SUCCES:签约成功;FAILED:签约失败;WAIT_CONFIRM: 签约登记成功;INVALID: 已解约 |
protocol_no | String(20) | Y | 银盛支付平台的签约流水号 |
banktype | String(30) | N | 行别,示例值:3012900 |
6.样例
6.1 SDK调用示例
- 银盛将与服务端交互的接口封装在开发工具包(SDK)中,开发者无需自行实现同服务端交互的复杂逻辑,直接将SDK导入自己的工程后,通过sdk示例代码实现同银盛服务端的交互。
@Test
public void queryProtocol() throws Exception {
/**1、获取需要的参数*/
OnlineReqDataVo req = new OnlineReqDataVo();
//快捷协议查询的请求路径,建议配置在项目的配置文件里面
String reqUrl = "https://trusteeship.ysepay.com/gateway.do";
//客户端私钥证书路径: 证书是在入网流程中自己申请的
String privateKeyFilePath = "D:\\openRSA\\hyfz_test2.pfx";
//客户端私钥密钥: 私钥密钥在入网流程中自己申请私钥证书时填写的
String privateKeyPassworde = "123456";
//银盛公钥证书路径: 证书入网申请后随邮件发放
String publicKeyFilePath = "D:\\openRSA\\businessgate.cer";
//商户在银盛支付平台开设的用户号[商户号]:入网申请后发放
String partnerId = "hyfz_test2";
//设置私钥证书路径
req.setPrivateKeyFilePath(privateKeyFilePath);
//设置私钥密钥
req.setPrivateKeyPassword(privateKeyPassworde);
//设置ys公钥证书路径
req.setYsPublicKeyFilePath(publicKeyFilePath);
//设置请求路径
req.setReqUrl(reqUrl);
//设置通知路径
req.setPartnerId(partnerId);
/**2、组装业务参数*/
Map<String,Object> bizContentMap = new HashMap<>();
bizContentMap.put("protocol_no","K2021101436720150055");//银盛支付平台的签约流水号:商户签约确认接口(mercSignConfirm)返回的protocol_no
req.setParamData(bizContentMap);
logger.info("快捷协议查询请求入参为:"+ JSONObject.toJSONString(req));
/**2、调用API的方法*/
String result = null;
try{
result = TrusteeshipApi.queryProtocol(req);
//根据返回结果处理自己的业务逻辑,result内容详见接口文档
}catch (Exception e){
logger.info("快捷协议查询失败:"+e.getCause().getMessage());
e.printStackTrace();
//根据自己要求处理业务逻辑
}
}
7.附录
7.1 请求错误码
错误码 | 错误描述 | 解决方案 |
---|---|---|
ACQ.SYSTEM_ERROR | 接口返回错误 | 该笔签约订单异常 |
ACQ.INVALID_PARAMETER | 参数无效 | 检查请求参数,修改后重新发起请求 |
ACQ.ACCESS_FORBIDDEN | 无权限使用接口 | 联系银盛市场人员进行签约 |