商户可通过填写账单编号等信息,使用账单查询类交易为持卡人提供如便民缴费、网上缴税、信用卡还款、保险缴费等相关的账单支付服务。账单查询类交易可由商户通过SDK向银联全渠道支付交易平台发起交易。
POST
https://gateway.95516.com/jiaofei/api/frontTransReq.do
https://gateway.test.95516.com/jiaofei/api/frontTransReq.do
中文名称 | 英文名称 | 域类型 | 默认值 | 请求要求 | 备注 | |
---|---|---|---|---|---|---|
编码方式 | encoding | ANS1..20 | UTF-8 | M-必填 | 默认取值:UTF-8 | |
签名 | signature | ANS1..1024 | 0 | M-必填 | 填写对报文摘要的签名 | |
产品类型 | bizType | N6 | 无 | M-必填 | 000601:账单支付 000902:Token支付 | |
接入类型 | accessType | N1 | 无 | M-必填 |
0:商户直连接入 1:收单机构接入 2:平台商户接入 |
|
商户代码 | merId | AN15 | 无 | M-必填 | ||
二级商户代码 | subMerId | AN5..15 | 无 | C-按条件必填 | 商户类型为平台类商户接入时必须上送 | |
二级商户名称 | subMerName | ANS1..40 | 无 | C-按条件必填 | 商户类型为平台类商户接入时必须上送 | |
二级商户简称 | subMerAbbr | ANS1…16 | 无 | C-按条件必填 | 商户类型为平台类商户接入时必须上送 | |
商户订单号 | orderId | AN8..40 | 无 | M-必填 |
商户订单号,不能含“-”或“_”; 商户自定义,同一交易日期内不可重复; 商户代码merId、商户订单号orderId、订单发送时间txnTime三要素唯一确定一笔交易。 |
|
订单发送时间 | txnTime | YYYYMMDDhhmmss | 无 | M-必填 | ||
交易币种 | currencyCode | AN3 | 无 | C-按条件必填 | 交易金额上送时,交易币种必送 默认156 | |
账号类型(卡介质) | accType | N2 | 无 | C-按条件必填 | 后台类交易且卡号上送时上送; 01:银行卡 02:存折 03:IC卡 默认取值:01 取值“03”表示以IC终端发起的IC卡交易,IC作为普通银行卡进行支付时,此域填写为“01” | |
账号 | accNo | AN1..1024 | 无 | C-按条件必填 | 1. 后台类交易需上送 2. 前台类交易如上送此域,页面上默认使用此卡支付,同时,持卡人也可以换用其他卡,如果想锁定只能使用这张卡,需要在保留域上送锁定卡标识,具体见注5 | |
发卡机构代码 | issInsCode | AN1..11 | 无 | C-按条件必填 |
网银支付,直接跳转至银行时必填(银行前移模式) |
|
银行卡验证信息及身份信息 | customerInfo | ANS1..1024 | 无 | O-选填 | 查看详情 | |
交易金额 | txnAmt | N1..12 | 无 | C-按条件必填 | 取查询返回的billDetailInfo中form 里面name 为amount的 formItem的value;如果没有name 为amount的可以不上送 | |
业务代码 | bussCode | ANS4..20 | 无 | M-必填 | busscode 三元组:账单类型_地区码_附加地区码 示例:D1_3300_0000 账单类型、地区码、附加地区码参考获取账单业务要素(BIZ)说明 | |
账单要素 | billQueryInfo | ANS1..2048 | 无 | C-按条件必填 | 查看详情 | |
保留域 | reserved | ANS1..2048 | 无 | C-按条件必填 | 查看详情 | |
终端号 | termId | ANS8 | 无 | C-按条件必填 | ||
持卡人IP | customerIp | NS7..40 | 无 | O-选填 | 前台交易,有IP防钓鱼要求的商户上送 | |
加密证书ID | encryptCertId | N1..128 | 无 | C-按条件必填 | ||
终端信息域 | userMac | ans80 | 无 | O-选填 | 移动支付业务需要上送 | |
渠道类型 | channelType | N2 | 无 | M-必填 | 07:互联网 08:移动 | |
签名方法 | signMethod | N2 | 无 | M-必填 | 非对称签名: 01(表示采用RSA签名) HASH表示散列算法 11:支持散列方式验证SHA-256 12:支持散列方式验证SM3 | |
分期付款信息域 | instalTransInfo | ANS1..128 | 无 | C-按条件必填 | 查看详情 | |
控制规则 | ctrlRule | N32 | 无 | O-选填 | 32位01字符串控制位,从左至右第四位取值为1时表示需要强制分期处理 | |
交易类型 | txnType | N2 | 无 | M-必填 | 13 | |
交易子类 | txnSubType | N2 | 无 | M-必填 | 01:便民缴费 03:信用卡还款 | |
前台通知地址 | frontUrl | ANS1..256 | 无 | C-按条件必填 | 交易前台返回商户结果时使用,前台类交易需上送 | |
后台通知地址 | backUrl | ANS1..256 | 无 | M-必填 |
后台返回商户结果时使用,如上送,则发送商户后台交易结果通知,不支持换行符等不可见字符,如需通过专线通知,需要在通知地址前面加上前缀:专线的首字母加竖线ZX| 如果不需要发后台通知,可以固定上送http://www.specialUrl.com |
|
请求方保留域 | reqReserved | ANS1..1024 | 无 | O-选填 | 商户自定义保留域,交易应答时会原样返回 | |
证书ID | certId | N1..128 | 无 | C-按条件必填 | ||
版本号 | version | NS5 | 无 | M-必填 | 固定填写 | |
原交易查询流水号 | origQryId | AN21 | 无 | C-按条件必填 | 先查询后缴费的交易,需上送查询交易应答的queryId | |
标记化支付信息域 | tokenPayData | ANS1..1024 | 无 | M-必填 | 查看详情 | |
收单机构代码 | acqInsCode | AN8..11 | 无 | C-按条件必填 |
接入类型为收单机构接入时需上送 |
中文名称 | 英文名称 | 域类型 | 默认值 | 请求要求 | 备注 | |
---|---|---|---|---|---|---|
编码方式 | encoding | ANS1..20 | UTF-8 | R-需要返回 | ||
签名 | signature | ANS1..1024 | 0 | M-必填 | ||
产品类型 | bizType | N6 | 无 | R-需要返回 | ||
接入类型 | accessType | N1 | 无 | R-需要返回 | 0:商户直连接入 1:收单机构接入 2:平台商户接入 |
|
商户代码 | merId | AN15 | 无 | R-需要返回 | ||
商户订单号 | orderId | AN8..40 | 无 | R-需要返回 | 商户订单号,不能含“-”或“_”; 商户自定义,同一交易日期内不可重复; 商户代码merId、商户订单号orderId、订单发送时间txnTime三要素唯一确定一笔交易。 |
|
订单发送时间 | txnTime | YYYYMMDDhhmmss | 无 | R-需要返回 | ||
支付方式 | payType | N4 | 无 | C-按条件必填 | 根据商户配置返回 | |
交易币种 | currencyCode | AN3 | 无 | R-需要返回 | ||
账号 | accNo | AN1..1024 | 无 | C-按条件必填 | 根据商户配置返回 | |
支付卡类型 | payCardType | N2 | 无 | C-按条件必填 | 根据商户配置返回 | |
交易金额 | txnAmt | N1..12 | 无 | R-需要返回 | ||
账单明细 | billDetailInfo | ANS1..2048 | 无 | O-选填 | 查看详情 | |
保留域 | reserved | ANS1..2048 | 无 | O-选填 | 查看详情 | |
查询流水号 | queryId | AN20..21 | 无 | M-必填 | 供后续查询用 | |
系统跟踪号 | traceNo | N6 | 无 | M-必填 | ||
交易传输时间 | traceTime | MMDDhhmmss | 无 | M-必填 | ||
清算日期 | settleDate | MMDD | 无 | M-必填 | ||
清算币种 | settleCurrencyCode | AN3 | 无 | M-必填 | ||
清算金额 | settleAmt | N1..12 | 无 | M-必填 | ||
清算汇率 | exchangeRate | N8 | 无 | C-按条件必填 | 交易成功,交易币种和清算币种不一致的时候返回 | |
兑换日期 | exchangeDate | MMDD | 无 | C-按条件必填 | 交易成功,交易币种和清算币种不一致的时候返回 | |
应答码 | respCode | AN2 | 无 | M-必填 | ||
应答信息 | respMsg | ANS1..256 | 无 | M-必填 | ||
支付卡标识 | payCardNo | ANS1..19 | 无 | C-按条件必填 | 移动支付交易时,根据商户配置返回 | |
支付卡名称 | payCardIssueName | ANS1..64 | 无 | C-按条件必填 | 移动支付交易时,根据商户配置返回 | |
签名方法 | signMethod | N2 | 无 | M-必填 | ||
签名公钥证书 | signPubKeyCert | AN1..2048 | 无 | C-按条件必填 | 此域填写银联签名公钥证书,使用RSA签名方式时,默认返回,如果ctrlRule第五位为1时,不返。 |
|
交易类型 | txnType | N2 | 无 | R-需要返回 | ||
交易子类 | txnSubType | N2 | 无 | R-需要返回 | ||
请求方保留域 | reqReserved | ANS1..1024 | 无 | R-需要返回 | ||
版本号 | version | NS5 | 无 | R-需要返回 | ||
收单机构代码 | acqInsCode | AN8..11 | 无 | C-按条件必填 | 接入类型为收单机构接入时需上送 |
String merId = req.getParameter("merId");
String orderId = req.getParameter("orderId");
String txnTime = req.getParameter("txnTime");
String txnAmt = req.getParameter("txnAmt");
String bussCode = req.getParameter("bussCode");
String billQueryInfo = req.getParameter("billQueryInfo");
String origQryId = req.getParameter("origQryId");
Map<String, String> data = new HashMap<String, String>();
/***银联全渠道系统,产品参数,除了encoding自行选择外其他不需修改***/
data.put("version", DemoBase.version); //版本号
data.put("encoding", DemoBase.encoding); //字符集编码 可以使用UTF-8,GBK两种方式
data.put("signMethod", SDKConfig.getConfig().getSignMethod()); //签名方法
data.put("txnType", "13"); //交易类型 13 账单支付
data.put("txnSubType", "01"); //交易子类型 01 便民缴费
data.put("bizType", "000601"); //业务类型
data.put("channelType", "07"); //渠道类型07-PC
data.put("accessType", "0"); //商户接入填0
/***商户接入参数***/
data.put("merId", merId); //商户号码(商户号码777290058110097仅做为测试调通交易使用,该商户号配置了需要对敏感信息加密)测试时请改成自己申请的商户号,【自己注册的测试777开头的商户号不支持代收产品】
data.put("orderId", orderId); //商户订单号,8-40位数字字母,不能含“-”或“_”,可以自行定制规则
data.put("txnTime", txnTime); //订单发送时间,格式为YYYYMMDDhhmmss,必须取当前时间,否则会报txnTime无效
data.put("currencyCode", "156");
data.put("txnAmt", txnAmt);
data.put("bussCode", bussCode);// 业务类型号,此处默认取demo演示页面传递的参数
data.put("billQueryInfo", AcpService.base64Encode(billQueryInfo,DemoBase.encoding));// 账单要素,根据前文显示要素列表由用户填写值,此处默认取demo演示页面传递的参数
if(null!=origQryId && ""!=origQryId){
data.put("origQryId", origQryId);// 先查后缴送账单查询应答报文的queryId,直接缴费的不送
}
data.put("frontUrl", DemoBase.frontUrl);//后台通知地址
data.put("backUrl", DemoBase.backUrl);//后台通知地址
// 请求方保留域,
// 透传字段,查询、通知、对账文件中均会原样出现,如有需要请启用并修改自己希望透传的数据。
// 出现部分特殊字符时可能影响解析,请按下面建议的方式填写:
// 1. 如果能确定内容不会出现&={}[]"'等符号时,可以直接填写数据,建议的方法如下。
//data.put("reqReserved", "透传信息1|透传信息2|透传信息3");
// 2. 内容可能出现&={}[]"'符号时:
// 1) 如果需要对账文件里能显示,可将字符替换成全角&={}【】“‘字符(自己写代码,此处不演示);
// 2) 如果对账文件没有显示要求,可做一下base64(如下)。
// 注意控制数据长度,实际传输的数据长度不能超过1024位。
// 查询、通知等接口解析时使用new String(Base64.decodeBase64(reqReserved), DemoBase.encoding);解base64后再对数据做后续解析。
//data.put("reqReserved", Base64.encodeBase64String("任意格式的信息都可以".toString().getBytes(DemoBase.encoding)));
// 订单超时时间。
// 超过此时间后,除网银交易外,其他交易银联系统会拒绝受理,提示超时。 跳转银行网银交易如果超时后交易成功,会自动退款,大约5个工作日金额返还到持卡人账户。
// 此时间建议取支付时的北京时间加15分钟。
// 超过超时时间调查询接口应答origRespCode不是A6或者00的就可以判断为失败。
data.put("payTimeout", new SimpleDateFormat("yyyyMMddHHmmss").format(new Date().getTime() + 15 * 60 * 1000));
/**请求参数设置完毕,以下对请求参数进行签名并生成html表单,将表单写入浏览器跳转打开银联页面**/
Map<String, String> reqData = AcpService.sign(data,DemoBase.encoding); //报文中certId,signature的值是在signData方法中获取并自动赋值的,只要证书配置正确即可。
String requestFrontUrl = SDKConfig.getConfig().getJfFrontRequestUrl(); //获取请求银联的前台地址:对应属性文件acp_sdk.properties文件中的acpsdk.frontTransUrl
String html = AcpService.createAutoFormHtml(requestFrontUrl, reqData,DemoBase.encoding); //生成自动跳转的Html表单
LogUtil.writeLog("打印请求HTML,此为请求报文,为联调排查问题的依据:"+html);
resp.getWriter().write(html); //将生成的html写到浏览器中完成自动跳转打开银联支付页面;这里调用signData之后,将html写到浏览器跳转到银联页面之前均不能对html中的表单项的名称和值进行修改,如果修改会导致验签不通过
LogUtil.writeLog("BackRcvResponse接收后台通知开始");
String encoding = req.getParameter(SDKConstants.param_encoding);
// 获取银联通知服务器发送的后台通知参数
Map<String, String> reqParam = getAllRequestParam(req);
LogUtil.printRequestLog(reqParam);
Map<String, String> valideData = null;
if (null != reqParam && !reqParam.isEmpty()) {
Iterator<Entry<String, String>> it = reqParam.entrySet().iterator();
valideData = new HashMap<String, String>(reqParam.size());
while (it.hasNext()) {
Entry<String, String> e = it.next();
String key = (String) e.getKey();
String value = (String) e.getValue();
valideData.put(key, value);
}
}
//重要!验证签名前不要修改reqParam中的键值对的内容,否则会验签不过
if (!AcpService.validate(valideData, encoding)) {
LogUtil.writeLog("验证签名结果[失败].");
//验签失败,需解决验签问题
} else {
LogUtil.writeLog("验证签名结果[成功].");
//【注:为了安全验签成功才应该写商户的成功处理逻辑】交易成功,更新商户订单状态
String orderId =valideData.get("orderId"); //获取后台通知的数据,其他字段也可用类似方式获取
String respCode = valideData.get("respCode");
}
LogUtil.writeLog("BackRcvResponse接收后台通知结束");
//返回给银联服务器http 200 状态码
resp.getWriter().print("ok");
1. 不返回报文体的情况:
版本号,交易类型、子类,签名方法,签名值等关键域未上送,返回“Invalid request.”;
交易类型和请求地址校验有误,返回“Invalid request URI.”
2. 返回全部的请求报文,附加应答码和应答描述(包括的应答码有:01、02、03、10、11、32):
验证签名失败;
报文格式错(包含,必填域缺失,上送银联报文未定义的域,报文域的格式非法,交易时间超出范围);
签名失败;
超时等其他系统异常