单笔代收协议签约授权
1.修订记录
修订 |
日期 |
说明 |
作者 |
V0.1 |
2017/8/2 |
新接口参数定义 |
黄月巧 |
V0.2 |
2017/9/11 |
去掉获取授权码返回null的内容 |
陈宋东 |
V0.3 |
2017/10/20 |
新增异常类型ACQ.BUSINESS_TIMEOUT_ERROR(业务超时) |
陈宋东 |
V0.4 |
2021/12/27 |
支持国密 |
王晶 |
2.接口说明
(1)场景说明
1、单笔代收协议签约授权
(2)接口说明
1、 单笔代收协议签约授权-V3.0版本
3.请求地址
4.单笔代收协议签约获取授权码
4.1公共请求参数
参数 |
类型(字节长度) |
必填 |
参数说明 |
method |
String(1,128) |
Y |
接口名称。固定值:ysepay.ds.protocol.single.accept.get.authorize.msg |
partner_id |
String(1,20) |
Y |
商户在银盛支付平台开设的用户号[商户号] |
timestamp |
String(1,19) |
Y |
发送请求的时间,格式"yyyy-MM-dd HH:mm:ss",示例值:2014-07-24 03:07:50 |
charset |
String(1,10) |
Y |
商户网站使用的编码格式,如utf-8、gbk、gb2312等。示例值:GBK |
sign_type |
String(1,10) |
Y |
签名类型,RSA/SM |
sign |
String(1,256) |
Y |
签名字符串,再用Base64编码 |
version |
String(1,3) |
Y |
接口版本3.0,当前版本:3.0 |
biz_content |
String |
Y |
业务请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递 |
4.2 业务请求参数
参数名biz_content,值为一个json格式对象,下面列表描述json对象的值
参数 |
类型(字节长度) |
必填 |
参数说明 |
protocol_no |
String(1,32) |
Y |
客户企业两方协议号 |
5.单笔代收协议签约授权接口
5.1 公共请求参数
参数 |
类型(字节长度) |
必填 |
参数说明 |
method |
String(1,128) |
Y |
接口名称。固定值:ysepay.ds.protocol.single.accep.authorize |
partner_id |
String(1,20) |
Y |
商户在银盛支付平台开设的用户号[商户号] |
timestamp |
String(1,19) |
Y |
发送请求的时间,格式"yyyy-MM-dd HH:mm:ss",示例值:2014-07-24 03:07:50 |
charset |
String(1,10) |
Y |
商户网站使用的编码格式,如utf-8、gbk、gb2312等。示例值:GBK |
sign_type |
String(1,10) |
Y |
签名类型,RSA/SM |
sign |
String(1,256) |
Y |
签名字符串,再用Base64编码 |
version |
String(1,3) |
Y |
接口版本 3.0,当前版本:3.0 |
biz_content |
String |
Y |
业务请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递 |
5.2 业务请求参数
参数名biz_content,值为一个json格式对象,下面列表描述json对象的值
参数 |
类型(字节长度) |
必填 |
参数说明 |
protocol_no |
String(1,32) |
Y |
客户企业两方协议号 |
bank_telephone_no |
String(1,11) |
Y |
银行预留手机号码 |
mobile_verify_code |
String(6,6) |
Y |
验证码,示例值:778666 |
5.3 响应参数说明
银盛支付对商户的短信验证码授权完成之后就会开始进行协议签约的处理,该同步返回指的是授权完成之后,银盛支付继续处理签约流程,授权接口会返回业务处理状态,短信验证码授权失败,那么会抛出异常。
请注意:银盛后期对返回参数保留扩展的权利,扩展方式为新增参数但不会删除参数,请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况
5.3.1 公共响应参数
参数 |
类型(字节长度) |
必填 |
参数说明 |
sign |
String |
Y |
签名字符串,Base64编码 |
ysepay_ds_protocol_single_accep_authorize_response |
String |
Y |
业务响应参数的集合,最大长度不限 |
5.3.2 业务响应参数
参数 |
类型(字节长度) |
必填 |
参数说明 |
code |
String |
Y |
响应代码 |
msg |
String |
Y |
响应代码描述 |
protocol_no |
String(1,32) |
Y |
客户企业两方协议号 |
protocol _status |
String(1,32) |
Y |
交易目前所处的状态。受理成功状态的值: PROTOCOL_ACCEPT_SUCCESS,示例值:附录8.2 |
protocol _status_description |
String(256) |
N |
状态描述,示例值:受理成功 |
6.异步通知参数说明
银盛支付在受理商户的协议签约请求,获取授权码请求,授权请求成功完成之后,会将协议签约的最终状态通过异步通知发送回给商户。
请注意:银盛后期对返回参数保留扩展的权利,扩展方式为新增参数但不会删除参数,请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
参数 |
类型(字节长度) |
必填 |
参数说明 |
protocol_no |
String(1,32) |
Y |
客户企业两方协议号 |
protocol _status |
String(1,32) |
Y |
交易目前所处的状态。受理成功状态的值: PROTOCOL_ACCEPT_SUCCESS,示例值:附录8.2 |
protocol _status_description |
String(256) |
N |
状态描述,示例值:受理成功 |
fee |
Number(10,2) |
N |
手续费 |
notify_type |
String |
Y |
通知类型,示例值:ysepay.ds.protocol.single.notify |
notify_time |
String(19) |
Y |
发送请求的时间,格式"yyyy-MM-dd HH:mm:ss",示例值:2014-07-24 03:07:50 |
sign_type |
String |
Y |
签名类型,交易请求时传入的签名类型RSA/SM |
sign |
String |
Y |
签名字符串,Base64编码 |
7.样例
7.1 sdk调用样例
- 银盛将与服务端交互的接口封装在开发工具包(SDK)中,开发者无需自行实现同服务端交互的复 杂逻辑,直接将SDK导入自己的工程后,通过sdk示例代码实现同银盛服务端的交互。
##########1、单笔代收协议签约获取授权码接口请求
/**1、获取需要的参数*/
//商户进件请求路径,建议配置在项目的配置文件里面
String reqUrl = "https://ds.ysepay.com/gateway.do";
//私钥证书存放路径,建议配置在项目的配置文件里面
String privateKeyFilePath = "D:\\openRSA\\hyfz_test2.pfx";
//ys公钥证书存放地址 建议配置在项目的配置文件里面
String publicKeyFilePath = "D:\\openRSA\\businessgate.cer";
//私钥证书密钥,建议配置在项目的配置文件里面
String privateKeyPassworde = "123456";
//商户在银盛支付平台开设的用户号[商户号],接入时需要替换成自己的
String partnerId = "hyfz_test2";
String notifyUrl = "http://127.0.0.1";
/**2、组装需要的参数*/
OnlineReqDataVo req = new OnlineReqDataVo();
//设置私钥证书路径
req.setPrivateKeyFilePath(privateKeyFilePath);
//设置私钥密钥
req.setPrivateKeyPassword(privateKeyPassworde);
//设置ys公钥证书路径
req.setYsPublicKeyFilePath(publicKeyFilePath);
//设置请求路径
req.setReqUrl(reqUrl);
req.setPartnerId(partnerId);
req.setNotifyUrl(notifyUrl);
Map<String,Object>paramData = new LinkedHashMap<>();
//客户企业两方协议号
paramData.put("protocol_no","20211013000001");
//业务员参数
req.setParamData(paramData);
logger.info("单笔代收协议签约获取授权码接口请求入参为:"+ JSONObject.toJSONString(req));
/**2、调用API的方法*/
String result = null;
try{
result = DsApi.singleProtocolAcceptGetAuthorizeMsgDs(req);
JSONObject jsonObject = JSON.parseObject(result, Feature.OrderedField);
//根据返回结果处理自己的业务逻辑,result内容详见接口文档
}catch (Exception e){
logger.info("单笔代收协议签约获取授权码接口失败:"+e.getCause().getMessage());
}
##########2、单笔代收协议签约授权接口请求
/*1、获取需要的参数/ //商户进件请求路径,建议配置在项目的配置文件里面 String reqUrl = "https://ds.ysepay.com/gateway.do";
//私钥证书存放路径,建议配置在项目的配置文件里面
String privateKeyFilePath = "D:\\openRSA\\hyfz_test2.pfx";
//ys公钥证书存放地址 建议配置在项目的配置文件里面
String publicKeyFilePath = "D:\\openRSA\\businessgate.cer";
//私钥证书密钥,建议配置在项目的配置文件里面
String privateKeyPassworde = "123456";
//商户在银盛支付平台开设的用户号[商户号],接入时需要替换成自己的
String partnerId = "hyfz_test2";
String notifyUrl = "http://127.0.0.1";
/**2、组装需要的参数*/
OnlineReqDataVo req = new OnlineReqDataVo();
//设置私钥证书路径
req.setPrivateKeyFilePath(privateKeyFilePath);
//设置私钥密钥
req.setPrivateKeyPassword(privateKeyPassworde);
//设置ys公钥证书路径
req.setYsPublicKeyFilePath(publicKeyFilePath);
//设置请求路径
req.setReqUrl(reqUrl);
req.setPartnerId(partnerId);
req.setNotifyUrl(notifyUrl);
Map<String,Object>paramData = new LinkedHashMap<>();
//客户企业两方协议号
paramData.put("protocol_no","20211013000001");
//银行预留手机号码
paramData.put("bank_telephone_no","18512345678");
//验证码
paramData.put("mobile_verify_code","778666");
//业务员参数
req.setParamData(paramData);
logger.info("单笔代收协议签约授权接口请求入参为:"+ JSONObject.toJSONString(req));
/**2、调用API的方法*/
String result = null;
try{
result = DsApi.singleProtocolAcceptGetAuthorizeDs(req);
JSONObject jsonObject = JSON.parseObject(result, Feature.OrderedField);
//根据返回结果处理自己的业务逻辑,result内容详见接口文档
}catch (Exception e){
logger.info("单笔代收协议签约授权接口请求失败:"+e.getCause().getMessage());
}
8.附录
8.1 业务错误码
错误码 |
错误描述 |
解决方案 |
ACQ.SYSTEM_ERROR |
系统错误 |
请调用查询接口查询协议状态 |
ACQ.BUSINESS_TIMEOUT_ERROR |
业务超时 |
请调用查询接口查询订单状态 |
ACQ.SUB_SYS_CHECK_CUSTINFO |
该协议中存在空要素(手机号码,流水号,验证码),业务检查不通过 |
调用查询接口查询协议的信息,并联系银盛客服处理 |
ACQ.INVALID_PARAMETER |
无效的业务参数 找不到对应的客户信息,检查发起参数 |
|
ACQ.SUB_SYS_CHECK_TIME_LIM |
当前请求过于频繁,请稍后重试 |
每次获取授权码之后,需等待30秒后才能重新获取,还需等待30秒 |
ACQ.CONNECTIONT_ERROR |
连接子系统出错 |
请联系客服或市场技术支持人员 |
ACQ.PROTOCOL_STATE_ERROR |
待授权协议状态错误,当前状态不允许发送或验证授权码 |
调用查询接口查询协议的信息,查询当前协议状态是否可以发起请求 |
ACQ.PROTOCOL_NOT_EXIST |
查询不到对应协议信息 |
请检查参数中的协议号是存在 |
ACQ.SYSTEM_ERROR |
系统错误 |
请联系银盛客户或者市场技术支持 |
ACQ.PROTOCOL_TEL_VALID_ERROR |
传递的手机号码与协议中付款方所留号码不一致 |
请检查协议中的手机号码 |
ACQ.PROTOCOL_VALID_OVERTIME |
授权码超时,请重新获取并再次发起请求 |
授权码120s有效,超时验证失败,请重新获取 |
ACQ.ACQ.PROTOCOL_VALID_ERROR |
授权码验证错误,请重新输入或者重新获取并再次发起请求 |
验证失败,请重新输入或者重新获取并再次发起请求 |
ACQ.PROTOCOL_EXISTED |
协议已经存在 |
协议已经存在不需要重新签订 |
ACQ.PROTOCOL_BUZICODE.ERROR |
代收协议不支持此业务代码 |
检查业务代码或者联系银盛客服 |
ACQ.PROXY_CHECK_FAILD |
代理关系检查失败 |
比如委托关系不存在 |
ACQ.PROXY_CHECK_PARAM |
代理关系参数验证失败 |
比如代理密码解密失败,或者代理密码与委托商户号没有同时传或者同时不传 |
8.2 交易状态
枚举名称 |
枚举说明 |
PROTOCOL_ACCEPT_SUCCESS |
签约请求受理成功,正在审核 |
PROTOCOL_EFFECT |
生效 |
PROTOCOL_INVALID |
无效 |
PROTOCOL_WAIT_AUTHORIZE |
协议待授权 |
PROTOCOL_AUTHORIZED |
协议已授权 |