银行实名认证三、四要素
1.修订记录
修订 | 日期 | 说明 | 作者 |
---|---|---|---|
V0.1 | 2016/11/29 | 新接口参数定义 | 莫尚校 |
V0.2 | 2018/05/25 | 补充shopdate参数 | 黄国强 |
V0.3 | 2021/12/27 | 支持国密 | 王晶 |
2.接口说明
(1)场景说明
1、提供姓名、手机号、账号、身份证号进行三、四要素认证
(2)接口说明
1、银行实名认证三、四要素下单接口
3.请求地址
环境 | HTTPS请求地址 |
---|---|
正式环境 | https://openapi.ysepay.com/gateway.do |
4.请求参数说明
4.1 公共请求参数
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
method | String(1,128) | Y | 接口名称 固定值 ysepay.authenticate.four.key.element |
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对象的值
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
out_trade_no | String(1,32) | Y | 商户系统生成的订单号,生成规则前8位必须为交易日期,如20180525,范围跨度支持包含当天在内的前后一天,且只能由大小写英文字母、数字、下划线及横杠组成 示例值:201805256843192280647118 |
shopdate | String(8,8) | Y | 商户系统的交易发生日期格式yyyyMMdd 示例值:20180525 |
bank_account_name | String(1,100) | Y | 实名认证姓名 |
bank_account_no | String(15,19) | Y | 银行帐号,支持对公对私 |
bank_mobile | String(11) | N | 银行预留手机号码,填写为四要素验证,不填写为三要素验证 |
id_card | String(50) | Y | 证件号码,目前只支持身份证 |
5.响应参数说明
银盛支付对商户的请求数据处理完成后,会将处理的结果数据同步回执给商户。
请注意:银盛后期会对返回参数保留扩展的权力,扩展方式为新增参数但不会删除参数,请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
5.1 公共响应参数
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
sign | String | Y | 签名字符串,Base64编码 |
ysepay_authenticate_four_key_element_response | String | Y | 业务响应参数的集合,最大长度不限 |
5.2 业务响应参数
银盛支付对商户的请求数据受理完成后,会将处理的结果数据同步回执给商户。
请注意:银盛后期会对返回参数保留扩展的权力,扩展方式为新增参数但不会删除参数,请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
参数 | 类型(字节长度) | 必填 | 参数说明 |
---|---|---|---|
code | String | Y | 响应代码 |
msg | String | Y | 响应代码描述 |
out_trade_no | String(1,32) | Y | 商户系统生成的订单号 |
trade_no | String(16) | N | 银盛支付交易流水号 |
fee | Number(15) | N | 参考手续费,单位为:RMB Yuan。取值范围为[0.01,100000000.00],精确到小数点后两位。 |
order_status | String(32) | Y | 实名认证目前所处的状态。实名认证状态的值: SUCCESS|FAILURE具体详情看下文中的1.4实名认证状态详解 |
order_status_description | String(256) | N | 状态描述,当order_status_description 为FAILURE时,该字段是实名认证失败原因描述。该参数最长为128个汉字。 |
6.样例
6.1 sdk调用示例
- 银盛将与服务端交互的接口封装在开发工具包(SDK)中,开发者无需自行实现同服务端交互的复杂逻辑,直接将SDK导入自己的工程后,通过sdk示例代码实现同银盛服务端的交互
OnlineReqDataVo req = new OnlineReqDataVo();
//请求路径,建议配置在项目的配置文件里面
String reqUrl = "https://openapi.ysepay.com/gateway.do";
//私钥证书存放路径,建议配置在项目的配置文件里面
String privateKeyFilePath = "D:\\opensdk\\hyfz_test2.pfx";
//ys公钥证书存放地址 建议配置在项目的配置文件里面
String publicKeyFilePath = "D:\\opensdk\\businessgate.cer";
//私钥证书密钥,建议配置在项目的配置文件里面
String privateKeyPassworde = "123456";
//商户在银盛支付平台开设的用户号[商户号],接入时需要替换成自己的
req.setPartnerId("hyfz_test2");
req.setReqUrl(reqUrl);
req.setPrivateKeyFilePath(privateKeyFilePath);
req.setPrivateKeyPassword(privateKeyPassworde);
req.setYsPublicKeyFilePath(publicKeyFilePath);
//银行实名认证三、四要素下单业务参数
Map<String, Object> bizContent = new HashMap<>();
bizContent.put("out_trade_no", "20211012175144035102000788376200");//商户生成的订单号,生成规则前8位必须为交易日期,如20180525,范围跨度支持包含当天在内的前后一天
bizContent.put("shopdate", "20211012");//商户日期(该参数做交易与查询时需要一致)该日期需在当日的前后一天时间范围之内
bizContent.put("bank_account_name", "李四");//实名认证姓名--请填写真实信息
bizContent.put("bank_account_no", "6212260488888888888");//银行帐号,支持对公对私
bizContent.put("bank_mobile", "18688888888");//银行预留手机号码,填写为四要素验证,不填写为三要素验证
bizContent.put("id_card","41022319940916602X");//证件号码,目前只支持身份证
req.setParamData(bizContent);
String result = null;
try{
logger.info("银行实名认证三、四要素调用sdk接口addScanMerc请求入参为:"+ JSONObject.toJSONString(req));
//根据返回结果处理自己的业务逻辑,result内容详见接口文档
result = BankAuthorityApi.sendBankAuthFourKey(req);
}catch (Exception e){
logger.info("银行实名认证三、四要素失败:"+ e.getMessage());
}
7.附录
7.1 实名认证错误码
错误码 | 错误描述 | 解决方案 |
---|---|---|
AQC.SYSTEM_ERROR | 系统错误 | 请调用查询接口查询订单状态 |
ACQ.INVALID_PARAMETER | 参数无效 | 检查请求参数,修改后重新发起请求 |
ACQ.PARAM_ERROR | 参数错误 | 检查请求参数,修改后重新发起请求 |
ACQ.RISK_ERROR | 风控检查异常 | 请检查风控是否有异常,然后再重新发起 |
ACQ.SYSTEM_BUSY | 系统繁忙 | 请稍后再试,如还有问题,请联系银盛 |
ACQ.RETURN_ERROR | 实名认证回执异常 | 请稍后再试,如还有问题,请联系银盛 |
7.2 实名认证状态
枚举名称 | 枚举说明 |
---|---|
SUCCESS | 实名认证成功 |
FAILURE | 实名认证失败 |