银联全渠道支付开通交易用于开通银行卡的银联全渠道支付功能。
POST
https://gateway.95516.com/gateway/api/frontTransReq.do
https://gateway.test.95516.com/gateway/api/frontTransReq.do
中文名称 | 英文名称 | 域类型 | 默认值 | 请求要求 | 备注 | |
---|---|---|---|---|---|---|
编码方式 | encoding | ANS1..20 | UTF-8 | M-必填 | 默认取值:UTF-8 | |
签名 | signature | ANS1..1024 | 0 | M-必填 | 填写对报文摘要的签名 | |
产品类型 | bizType | N6 | 无 | M-必填 | 000301:认证支付2.0 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-必填 | 商户发送交易时间 | |
账号类型(卡介质) | accType | N2 | 无 | O-选填 | ||
账号 | accNo | AN1..1024 | 无 | C-按条件必填 | 产品类型为Token时不上送 | |
银行卡验证信息及身份信息 | customerInfo | ANS1..1024 | 无 | O-选填 | 查看详情 | |
账单要素 | billQueryInfo | ANS1..2048 | 无 | C-按条件必填 | 查看详情 | |
保留域 | reserved | ANS1..2048 | 无 | O-选填 | 查看详情 | |
加密证书ID | encryptCertId | N1..128 | 无 | C-按条件必填 | ||
风控信息域 | riskRateInfo | ANS 1..2048 | 无 | O-选填 | 查看详情 | |
渠道类型 | channelType | N2 | 无 | M-必填 | ||
签名方法 | signMethod | N2 | 无 | M-必填 | 非对称签名: 01(表示采用RSA签名) HASH表示散列算法 11:支持散列方式验证SHA-256 12:支持散列方式验证SM3 | |
控制规则 | ctrlRule | N32 | 无 | C-按条件必填 | 32位01字符串控制位,从左至右第一位表示财税库银信息控制位,当第一位为1时,财税库银行业信息域taxIndustryInfo必上送 | |
交易类型 | txnType | N2 | 无 | M-必填 | 取值:79 | |
交易子类 | txnSubType | N2 | 无 | M-必填 | 00——默认开通 | |
前台通知地址 | 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-必填 |
固定填写5.1.0 |
|
标记化支付信息域 | tokenPayData | ANS1..1024 | 无 | M-必填 | 查看详情 | |
商户名称 | merName | ANS1..40 | 无 | C-按条件必填 |
接入类型为收单机构接入时需上送 不支持换行符等不可见字符 |
|
商户类别 | merCatCode | N4 | 无 | C-按条件必填 |
填写MCC码,接入类型为收单机构接入时需上送 |
|
收单机构代码 | acqInsCode | AN8..11 | 无 | C-按条件必填 |
已被批准加入银联互联网系统的收单机构代码 |
|
商户简称 | merAbbr | ANS1..8 | 无 | C-按条件必填 |
接入类型为收单机构接入时需上送 最长8位,不支持换行符等不可见字符 |
中文名称 | 英文名称 | 域类型 | 默认值 | 请求要求 | 备注 | |
---|---|---|---|---|---|---|
编码方式 | 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-需要返回 | ||
账号 | accNo | AN1..1024 | 无 | M-必填 | 产品类型为Token支付时,根据商户配置返回后四位,或返回前六位和后四位,或返回全卡号;认证支付返回全卡号 | |
支付卡类型 | payCardType | N2 | 无 | C-按条件必填 | 根据商户配置是否返回 | |
发卡机构代码 | issInsCode | AN1..11 | 无 | C-按条件必填 | 返回银行简码。银行简码列表参考附录:C.3 |
|
银行卡验证信息及身份信息 | customerInfo | ANS1..1024 | 无 | O-选填 | 查看详情 | |
保留域 | reserved | ANS1..2048 | 无 | O-选填 | 查看详情 | |
应答码 | respCode | AN2 | 无 | M-必填 | ||
应答信息 | respMsg | ANS1..256 | 无 | M-必填 | ||
开通状态 | activateStatus | N1 | 无 | M-必填 | 0:未开通业务 |
|
风控信息域 | riskRateInfo | ANS 1..2048 | 无 | O-选填 | 查看详情 | |
签名方法 | signMethod | N2 | 无 | M-必填 | ||
签名公钥证书 | signPubKeyCert | AN1..2048 | 无 | C-按条件必填 | 此域填写银联签名公钥证书,使用RSA签名方式时,默认返回,如果ctrlRule第五位为1时,不返。 |
|
交易类型 | txnType | N2 | 无 | R-需要返回 | 取值:79 | |
交易子类 | txnSubType | N2 | 无 | R-需要返回 | 默认:00 | |
请求方保留域 | reqReserved | ANS1..1024 | 无 | R-需要返回 | ||
版本号 | version | NS5 | 无 | R-需要返回 | 固定填写5.1.0 |
|
标记化支付信息域 | tokenPayData | ANS1..1024 | 无 | 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-需要返回 | ||
账号 | accNo | AN1..1024 | 无 | M-必填 | 产品类型为Token支付时,返回卡后4位;认证支付返回全卡号 | |
支付卡类型 | payCardType | N2 | 无 | M-必填 | ||
发卡机构代码 | issInsCode | AN1..11 | 无 | C-按条件必填 | 返回银行简码。银行简码列表参考附录:C.3 |
|
银行卡验证信息及身份信息 | customerInfo | ANS1..1024 | 无 | O-选填 | 查看详情 | |
保留域 | reserved | ANS1..2048 | 无 | O-选填 | 查看详情 | |
应答码 | respCode | AN2 | 无 | M-必填 | ||
应答信息 | respMsg | ANS1..256 | 无 | M-必填 | ||
开通状态 | activateStatus | N1 | 无 | M-必填 | 0:未开通业务 |
|
风控信息域 | riskRateInfo | ANS 1..2048 | 无 | O-选填 | 查看详情 | |
签名方法 | signMethod | N2 | 无 | M-必填 | ||
签名公钥证书 | signPubKeyCert | AN1..2048 | 无 | C-按条件必填 | 此域填写银联签名公钥证书,使用RSA签名方式时,默认返回,如果ctrlRule第五位为1时,不返。 |
|
交易类型 | txnType | N2 | 无 | R-需要返回 | 取值:79 | |
交易子类 | txnSubType | N2 | 无 | R-需要返回 | 默认:00 | |
请求方保留域 | reqReserved | ANS1..1024 | 无 | R-需要返回 | ||
版本号 | version | NS5 | 无 | R-需要返回 | 固定填写5.1.0 |
|
标记化支付信息域 | tokenPayData | ANS1..1024 | 无 | C-按条件必填 | 查看详情 |
@Override
protected void doPost(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
resp.setContentType("text/html; charset="+ DemoBase.encoding);
String merId = req.getParameter("merId");
String orderId = req.getParameter("orderId");
String txnTime = req.getParameter("txnTime");
/**
* 组装请求报文
*/
Map<String, String> contentData = new HashMap<String, String>();
/***银联全渠道系统,产品参数,除了encoding自行选择外其他不需修改***/
contentData.put("version", DemoBase.version); //版本号
contentData.put("encoding", DemoBase.encoding); //字符集编码 可以使用UTF-8,GBK两种方式
contentData.put("signMethod", SDKConfig.getConfig().getSignMethod()); //签名方法
contentData.put("txnType", "79"); //交易类型 11-代收
contentData.put("txnSubType", "00"); //交易子类型 00-默认开通
contentData.put("bizType", "000301"); //业务类型 认证支付2.0
contentData.put("channelType", "07"); //渠道类型07-PC
/***商户接入参数***/
contentData.put("merId", merId); //商户号码(本商户号码仅做为测试调通交易使用,该商户号配置了需要对敏感信息加密)测试时请改成自己申请的商户号,【自己注册的测试777开头的商户号不支持代收产品】
contentData.put("accessType", "0"); //接入类型,商户接入固定填0,不需修改
contentData.put("orderId", orderId); //商户订单号,8-40位数字字母,不能含“-”或“_”,可以自行定制规则
contentData.put("txnTime", txnTime); //订单发送时间,格式为YYYYMMDDhhmmss,必须取当前时间,否则会报txnTime无效
contentData.put("accType", "01"); //账号类型
//选送卡号、手机号、证件类型+证件号、姓名
//也可以都不送,在界面输入这些要素
//此测试商户号777290058110097 后台开通业务只支持 贷记卡
Map<String,String> customerInfoMap = new HashMap<String,String>();
customerInfoMap.put("certifTp", "01"); //证件类型
customerInfoMap.put("certifId", "341126197709218366"); //证件号码
customerInfoMap.put("customerNm", "全渠道"); //姓名
customerInfoMap.put("phoneNo", "13552535506"); //手机号
////////////如果商户号开通了【商户对敏感信息加密】的权限那么需要对 accNo,pin和phoneNo,cvn2,expired加密(如果这些上送的话),对敏感信息加密使用:
String accNo = AcpService.encryptData("6216261000000000018", "UTF-8"); //这里测试的时候使用的是测试卡号,正式环境请使用真实卡号
contentData.put("accNo", accNo);
contentData.put("encryptCertId",AcpService.getEncryptCertId()); //加密证书的certId,配置在acp_sdk.properties文件 acpsdk.encryptCert.path属性下
String customerInfoStr = AcpService.getCustomerInfoWithEncrypt(customerInfoMap,null,DemoBase.encoding);
contentData.put("customerInfo", customerInfoStr);
//////////
/////////如果商户号未开通【商户对敏感信息加密】权限那么不需对敏感信息加密使用:
//contentData.put("accNo", "6216261000000000018");
//String customerInfoStr = AcpService.getCustomerInfo(customerInfoMap,null,DemoBase.encoding_UTF8); //前台实名认证送支付验证要素 customerInfo中要素不要加密
//contentData.put("customerInfo", customerInfoStr);
////////
//前台通知地址 (需设置为外网能访问 http https均可),支付成功后的页面 点击“返回商户”的时候将异步通知报文post到该地址
//如果想要实现过几秒中自动跳转回商户页面权限,需联系银联业务申请开通自动返回商户权限
//注:如果开通失败的“返回商户”按钮也是触发frontUrl地址,点击时是按照get方法返回的,没有通知数据返回商户
contentData.put("frontUrl", DemoBase.frontUrl);
//后台通知地址(需设置为【外网】能访问 http https均可),支付成功后银联会自动将异步通知报文post到商户上送的该地址,失败的交易银联不会发送后台通知
//后台通知参数详见open.unionpay.com帮助中心 下载 产品接口规范 网关支付产品接口规范 消费交易 商户通知
//注意:1.需设置为外网能访问,否则收不到通知 2.http https均可 3.收单后台通知后需要10秒内返回http200或302状态码
// 4.如果银联通知服务器发送通知后10秒内未收到返回状态码或者应答码非http200,那么银联会间隔一段时间再次发送。总共发送5次,每次的间隔时间为0,1,2,4分钟。
// 5.后台通知地址如果上送了带有?的参数,例如:http://abc/web?a=b&c=d 在后台通知处理程序验证签名之前需要编写逻辑将这些字段去掉再验签,否则将会验签失败
contentData.put("backUrl", DemoBase.backUrl);
//contentData.put("reqReserved", "透传字段"); //请求方保留域,透传字段(可以实现商户自定义参数的追踪)本交易的后台通知,对本交易的交易状态查询交易、对账文件中均会原样返回,商户可以按需上传,长度为1-1024个字节。出现&={}[]符号时可能导致查询接口应答报文解析失败,建议尽量只传字母数字并使用|分割,或者可以最外层做一次base64编码(base64编码之后出现的等号不会导致解析失败可以不用管)。
//contentData.put("reserved", "{customPage=true}"); //如果开通页面需要使用嵌入页面的话,请上送此用法
// 订单超时时间。
// 超过此时间后,除网银交易外,其他交易银联系统会拒绝受理,提示超时。 跳转银行网银交易如果超时后交易成功,会自动退款,大约5个工作日金额返还到持卡人账户。
// 此时间建议取支付时的北京时间加15分钟。
// 超过超时时间调查询接口应答origRespCode不是A6或者00的就可以判断为失败。
contentData.put("payTimeout", new SimpleDateFormat("yyyyMMddHHmmss").format(new Date().getTime() + 15 * 60 * 1000));
/**请求参数设置完毕,以下对请求参数进行签名并生成html表单,将表单写入浏览器跳转打开银联页面**/
Map<String, String> reqData = AcpService.sign(contentData,DemoBase.encoding); //报文中certId,signature的值是在signData方法中获取并自动赋值的,只要证书配置正确即可。
String requestFrontUrl = SDKConfig.getConfig().getFrontRequestUrl(); //获取请求银联的前台地址:对应属性文件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("FrontRcvResponse前台接收报文返回开始");
String encoding = req.getParameter(SDKConstants.param_encoding);
LogUtil.writeLog("返回报文中encoding=[" + encoding + "]");
String pageResult = "";
if (DemoBase.encoding.equalsIgnoreCase(encoding)) {
pageResult = "/utf8_result.jsp";
} else {
pageResult = "/gbk_result.jsp";
}
Map<String, String> respParam = getAllRequestParam(req);
LogUtil.printRequestLog(respParam);
Map<String, String> valideData = null;
StringBuffer page = new StringBuffer();
if (null != respParam && !respParam.isEmpty()) {
Iterator<Entry<String, String>> it = respParam.entrySet()
.iterator();
valideData = new HashMap<String, String>(respParam.size());
while (it.hasNext()) {
Entry<String, String> e = it.next();
String key = (String) e.getKey();
String value = (String) e.getValue();
page.append("<tr><td width="30%" align="right">" + key
+ "(" + key + ")</td><td>" + value + "</td></tr>");
valideData.put(key, value);
}
}
if (!AcpService.validate(valideData, encoding)) {
page.append("<tr><td width="30%" align="right">验证签名结果</td><td>失败</td></tr>");
LogUtil.writeLog("验证签名结果[失败].");
} else {
page.append("<tr><td width="30%" align="right">验证签名结果</td><td>成功</td></tr>");
LogUtil.writeLog("验证签名结果[成功].");
System.out.println(valideData.get("orderId")); //其他字段也可用类似方式获取
String customerInfo = valideData.get("customerInfo");
if(null!=customerInfo){
Map<String,String> customerInfoMap = AcpService.parseCustomerInfo(customerInfo, "UTF-8");
page.append("customerInfo明文: "+customerInfoMap);
}
String accNo = valideData.get("accNo");
//如果返回的卡号是密文那么,可以用下边方法解密
if(null!=accNo){
accNo = AcpService.decryptData(accNo, "UTF-8");
page.append("<br>accNo明文: "+accNo);
}
String respCode = valideData.get("respCode");
//判断respCode=00、A6后,对涉及资金类的交易,请再发起查询接口查询,确定交易成功后更新数据库。
}
req.setAttribute("result", page.toString());
req.getRequestDispatcher(pageResult).forward(req, resp);
LogUtil.writeLog("FrontRcvResponse前台接收报文返回结束");
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 customerInfo = valideData.get("customerInfo");
if(null!=customerInfo){
Map<String,String> customerInfoMap = AcpService.parseCustomerInfo(customerInfo, "UTF-8");
LogUtil.writeLog("customerInfoMap明文: "+ customerInfoMap);
}
String accNo = valideData.get("accNo");
//如果配置了敏感信息加密证书,可以用以下方法解密
if(null!=accNo){
accNo = AcpService.decryptData(accNo, "UTF-8");
LogUtil.writeLog("accNo明文: "+ accNo);
}
String respCode = valideData.get("respCode");
//判断respCode=00、A6后,对涉及资金类的交易,请再发起查询接口查询,确定交易成功后更新数据库。
}
LogUtil.writeLog("BackRcvResponse接收后台通知结束");
//返回给银联服务器http 200状态码
resp.getWriter().print("ok");
1. 不返回报文体的情况:
版本号,交易类型、子类,签名方法,签名值等关键域未上送,返回“Invalid request.”;
交易类型和请求地址校验有误,返回“Invalid request URI.”
2. 返回全部的请求报文,附加应答码和应答描述(包括的应答码有:01、02、03、10、11、32):
验证签名失败;
报文格式错(包含,必填域缺失,上送银联报文未定义的域,报文域的格式非法,交易时间超出范围);
签名失败;
超时等其他系统异常