批量代付汇总查询
1.修订记录
修订 | 日期 | 说明 | 作者 |
---|---|---|---|
V0.1 | 2017/06/20 | 新接口参数定义 | 黄月巧 |
V0.2 | 2017/8/28 | 新增参数shopdate | 黄月巧 |
V0.3 | 2017/9/18 | 公共参数新加proxy_password和merchant_usercode参数 | 黄月巧 |
V0.4 | 2017/10/20 | 新增异常类型ACQ.BUSINESS_TIMEOUT_ERROR(业务超时) | 陈宋东 |
V0.5 | 2020/11/30 | 修改关于ACQ.SYSTEM.ERROR的中文描述 | 汤吉齐 |
V0.6 | 2021/01/21 | 修改关于ACQ.QUERY_NO_BATCH_RECORD的错误描述 | 王晶 |
V0.7 | 2021/12/27 | 支持国密 | 王晶 |
2.接口说明
(1)场景说明
1、批量代付汇总的查询
(2)接口说明
1、 批量代付明细查询接口
3.请求地址
环境 | HTTPS请求地址 |
---|---|
正式环境 | https://searchdf.ysepay.com/gateway.do |
4.请求参数说明
4.1公共请求参数
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
method | String(1,128) | Y | 接口名称。固定值:ysepay.df.batch.summary.query |
partner_id | String(1,20) | Y | 在银盛支付开设的服务商商户号,请联系客户经理提供 |
proxy_password | String(50) | N | 代理密码,加密传输 |
merchant_usercode | String(20) | N | 真实商户用户号,示例值:pinganyinhang02 |
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 |
biz_content | String | Y | 业务请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递 |
4.2 业务请求参数
参数名biz_content,值为一个json格式对象,下面列表描述json对象的值
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
out_batch_no | String(1,16) | Y | 商户批次号,示例值:F201703081234567 |
shopdate | String(8,8) | Y | 商户日期(该参数做交易与查询时需要一致)该日期需在当日的前后一天时间范围之内,示例值:20170308 |
5.同步返回参数说明
银盛支付对商户的请求数据处理完成后,会将处理的结果数据同步回执给商户。
请注意:银盛后期对返回参数保留扩展的权利,扩展方式为新增参数但不会删除参数,请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
5.1 公共响应参数
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
sign | String | Y | 签名字符串,Base64编码 |
ysepay_df_batch_summary_query_respose | String | Y | 业务响应参数的集合,最大长度不限 |
5.2 业务响应参数
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
code | String | Y | 响应代码 |
msg | String | Y | 响应代码描述 |
out_batch_no | String(16,16) | Y | 商户批次号,格式:F+15位唯一流水,建议格式:F+YYYYMMDD+XXXXXXX,示例值:F201703081234567 |
batch_no | String(1,30) | Y | 批次流水号 |
trade_status | String(1,32) | Y | 交易目前所处的状态。状态的值可为:BATCH_TRADE_SUCCESS等值,示例值:7.2 |
trade_status_description | String(256) | N | 状态描述,当trade_status为BATCH_TRADE_SUCCESS时,该字段是批次状态的描述。该参数最长为128个汉字。示例值:批次交易处理完成 |
total_amount | Number(10,2) | Y | 总金额 |
total_num | String(1,4) | Y | 总笔数 |
success_total_amount | Number(10,2) | Y | 成功总金额 |
success_total_num | String(1,6) | Y | 成功总笔数 |
fee | Number(10,2) | N | 参考手续费,单位为:RMB Yuan。取值范围为[0.01,100000000.00],精确到小数点后两位。 |
batch_account_date | String(1,10) | N | 批次会计日期:日账单格式为yyyyMMdd,示例值:20160413 |
6.样例
6.1 sdk样例
- 银盛将与服务端交互的接口封装在开发工具包(SDK)中,开发者无需自行实现同服务端交互的复 杂逻辑,直接将SDK导入自己的工程后,通过sdk示例代码实现同银盛服务端的交互。
/**1、获取需要的参数*/
//商户进件请求路径,建议配置在项目的配置文件里面
String reqUrl = "https://searchdf.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<>();
//商户批次号,格式:F+15位唯一流水,建议格式:F+YYYYMMDD+XXXXXXX只能由大小写英文字母、数字、下划线及横杠组成
paramData.put("out_batch_no","20211013000001");
//商户日期
paramData.put("shopdate","20211013");
//业务参数
req.setParamData(paramData);
logger.info("批量代付查询请求入参为:"+ JSONObject.toJSONString(req));
/**2、调用API的方法*/
String result = null;
try{
result = DfApi.batchSummaryQueryDf(req);
JSONObject jsonObject = JSON.parseObject(result, Feature.OrderedField);
//根据返回结果处理自己的业务逻辑,result内容详见接口文档
}catch (Exception e){
logger.info("批量代付查询失败:"+e.getCause().getMessage());
}
/**3、调用API的方法*/
String result = null;
try{
//FIXEDME 具体调用接口方法
result = DfApi.singleDsprotocolQuickDf(req);
/**4、处理响应参数*/
JSONObject jsonObject = JSON.parseObject(result, Feature.OrderedField);
//根据返回结果处理自己的业务逻辑,result内容详见接口文档
}catch (Exception e){
logger.info("单笔代付交易(代收协议)失败:"+e.getCause().getMessage());
}
7.附录
7.1 业务错误码
错误码 | 错误描述 | 解决方案 |
---|---|---|
ACQ.SYSTEM_ERROR | 系统错误 | 支付中该状态为未知状态,请勿当成失败状态处理,请等待支付通知或继续查询 |
ACQ.BUSINESS_TIMEOUT_ERROR | 业务超时 | 请调用查询接口查询订单状态 |
ACQ.INVALID_PARAMETER | 参数无效 | 检查请求参数,修改后重新发起请求 |
ACQ.QUERY_NO_BATCH_RECORD | 暂未查询到该批次记录 | 检查partner_id/out_batch_no/out_trade_no/shopdate后重试 |
ACQ.QUERY_NO_RECORD | 暂未查询到记录 | 该状态为未知状态,请勿当成失败状态处理 检查传入的订单号是否正确,修改后重新发起请求或继续查询 |
ACQ.PROXY_CHECK_FAILD | 代理关系检查失败 | 比如委托关系不存在 |
ACQ.PROXY_CHECK_PARAM | 代理关系参数验证失败 | 比如代理密码解密失败,或者代理密码与委托商户号没有同时传或者同时不传 |
7.2 批次交易状态
枚举名称 | 枚举说明 |
---|---|
BATCH_ACCEPT_SUCCESS | 批次受理成功。 |
BATCH_TRADE_SUCCESS | 批次交易处理完成 |
BATCH_TRADE_FAILURE | 批次交易处理失败 |