预授权交易用于受理方向持卡人的发卡方确认交易许可。受理方将预估的消费金额作为预授权金额,发送给持卡人的发卡方。
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-必填 | 000201 | |
接入类型 | 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-必填 | 商户发送交易时间 | |
订单接收超时时间 | orderTimeout | N1..10 | 无 | O-选填 | 1、前台类消费交易时上送 2、认证支付2.0,后台交易时可选 | |
支付超时时间 | payTimeout | YYYYMMDDhhmmss | 无 | O-选填 | 超过此时间用户支付成功的交易,不通知商户,系统自动退款,大约5个工作日金额返还到用户账户 | |
默认支付方式 | defaultPayType | N4 | 无 | O-选填 | C 取值参考数据元说明 | |
支持支付方式 | supPayType | AN1..128 | 无 | O-选填 | 仅仅pc使用,使用哪种支付方式 由收单机构填写,取值为以下内容的一种或多种,通过逗号(,)分割。取值参考数据字典 | |
交易币种 | currencyCode | AN3 | 无 | M-必填 | 默认为156 | |
账号类型(卡介质) | accType | N2 | 无 | C-按条件必填 | 跨行收单且收单机构收集银行卡信息时上送 01:银行卡 02:存折 03:C卡 默认取值:01 取值“03”表示以IC终端发起的IC卡交易,IC作为普通银行卡进行支付时,此域填写为“01” | |
账号 | accNo | AN1..1024 | 无 | C-按条件必填 | 1、 后台类消费交易时上送全卡号或卡号后4位 2、 跨行收单且收单机构收集银行卡信息时上送、 3、前台类交易可通过配置后返回,卡号可选上送 | |
发卡机构代码 | issInsCode | AN1..11 | 无 | O-选填 |
1、当账号类型为02-存折时需填写 2、在前台类交易时填写默认银行代码,支持直接跳转到网银。银行简码列表参考附录:C.1、C.2, 其中C.2银行列表仅支持借记卡 |
|
银行卡验证信息及身份信息 | customerInfo | ANS1..1024 | 无 | C-按条件必填 | 查看详情 | |
交易金额 | txnAmt | N1..12 | 无 | M-必填 | 单位为分 | |
保留域 | reserved | ANS1..2048 | 无 | O-选填 | 查看详情 | |
终端号 | termId | ANS8 | 无 | O-选填 | ||
持卡人IP | customerIp | NS7..40 | 无 | O-选填 | 前台交易,有IP防钓鱼要求的商户上送 | |
加密证书ID | encryptCertId | N1..128 | 无 | C-按条件必填 | ||
终端信息域 | userMac | ans80 | 无 | O-选填 | 移动支付业务需要上送 | |
风控信息域 | riskRateInfo | ANS 1..2048 | 无 | O-选填 | 查看详情 | |
失败交易前台跳转地址 | frontFailUrl | ANS1..256 | 无 | O-选填 | 前台消费交易若商户上送此字段,则在支付失败时,页面跳转至商户该URL(不带交易信息,仅跳转) | |
有卡交易信息域 | cardTransData | ANS1Trans | 无 | C-按条件必填 | 查看详情 | |
渠道类型 | channelType | N2 | 无 | M-必填 | ||
签名方法 | signMethod | N2 | 无 | M-必填 | 非对称签名: 01(表示采用RSA签名) HASH表示散列算法 11:支持散列方式验证SHA-256 12:支持散列方式验证SM3 | |
订单描述 | orderDesc | ANS1..32 | 无 | C-按条件必填 | 移动支付上送 | |
预付卡通道 | accountPayChannel | ANS1..20 | 无 | C-按条件必填 | 预付卡的专享支付页面 | |
交易类型 | txnType | N2 | 无 | M-必填 | 02 | |
交易子类 | txnSubType | N2 | 无 | M-必填 | 01 | |
前台通知地址 | 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 |
中文名称 | 英文名称 | 域类型 | 默认值 | 请求要求 | 备注 | |
---|---|---|---|---|---|---|
编码方式 | encoding | ANS1..20 | UTF-8 | R-需要返回 | ||
签名 | signature | ANS1..1024 | 0 | M-必填 | ||
产品类型 | bizType | N6 | 无 | R-需要返回 | ||
接入类型 | accessType | N1 | 无 | R-需要返回 | 0:商户直连接入 1:收单机构接入 2:平台商户接入 |
|
收单机构代码 | acqInsCode | AN8..11 | 无 | C-按条件必填 | 接入类型为收单机构接入时需上送 | |
商户代码 | merId | AN15 | 无 | R-需要返回 | ||
商户订单号 | orderId | AN8..40 | 无 | R-需要返回 | 商户订单号,不能含“-”或“_”; 商户自定义,同一交易日期内不可重复; 商户代码merId、商户订单号orderId、订单发送时间txnTime三要素唯一确定一笔交易。 |
|
订单发送时间 | txnTime | YYYYMMDDhhmmss | 无 | R-需要返回 | ||
支付方式 | payType | N4 | 无 | C-按条件必填 | 根据商户配置返回 | |
交易币种 | currencyCode | AN3 | 无 | R-需要返回 | 默认为156 | |
账号 | accNo | AN1..1024 | 无 | C-按条件必填 | 根据商户配置返回 | |
支付卡类型 | payCardType | N2 | 无 | C-按条件必填 | 根据商户配置返回 | |
交易金额 | txnAmt | N1..12 | 无 | R-需要返回 | ||
保留域 | reserved | ANS1..2048 | 无 | O-选填 | 查看详情 | |
查询流水号 | queryId | AN20..21 | 无 | M-必填 | 预授权交易的流水号,供后续查询用 | |
应答码 | respCode | AN2 | 无 | M-必填 | ||
应答信息 | respMsg | ANS1..256 | 无 | M-必填 | ||
银联受理订单号 | tn | N21 | 无 | C-按条件必填 | 商户推送订单后银联移动支付系统返回该流水号,商户调用支付控件时使用 | |
签名方法 | signMethod | N2 | 无 | M-必填 | ||
签名公钥证书 | signPubKeyCert | AN1..2048 | 无 | C-按条件必填 | 此域填写银联签名公钥证书,使用RSA签名方式时,默认返回,如果ctrlRule第五位为1时,不返。 |
|
交易类型 | txnType | N2 | 无 | R-需要返回 | ||
交易子类 | txnSubType | N2 | 无 | R-需要返回 | ||
请求方保留域 | reqReserved | ANS1..1024 | 无 | R-需要返回 | ||
版本号 | version | NS5 | 无 | R-需要返回 |
中文名称 | 英文名称 | 域类型 | 默认值 | 请求要求 | 备注 | |
---|---|---|---|---|---|---|
编码方式 | 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 | 无 | M-必填 | 默认为156 | |
账号 | accNo | AN1..1024 | 无 | C-按条件必填 | 根据商户配置返回 | |
支付卡类型 | payCardType | N2 | 无 | C-按条件必填 | 根据商户配置返回 | |
交易金额 | txnAmt | N1..12 | 无 | R-需要返回 | ||
绑定标识号 | bindId | ANS1..128 | 无 | R-需要返回 | 绑定支付时,根据商户配置返回 | |
保留域 | 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-需要返回 |
Map<String, String> contentData = new HashMap<String, String>();
/***
银联全渠道系统,产品参数,除了encoding自行选择外其他不需修改***/
//
版本号
contentData.put("version", DemoBase.version);
//
字符集编码 可以使用UTF-8,GBK两种方式
contentData.put("encoding", DemoBase.encoding_UTF8);
//
签名方法
contentData.put("signMethod", SDKConfig.getConfig().getSignMethod());
//
交易类型 ,02:预授权
requestData.put("txnType", "02");
//
交易子类型, 01:预授权
requestData.put("txnSubType", "01");
//
业务类型 认证支付2.0
contentData.put("bizType", "000201");
//
渠道类型07-PC
contentData.put("channelType", "07");
/***
商户接入参数***/
//
商户号码(本商户号码仅做为测试调通交易使用,该商户号配置了需要对敏感信息加密)
//
测试时请改成自己申请的商户号,【自己注册的测试777开头的商户号不支持代收产品】
contentData.put("merId", merId);
//
接入类型,商户接入固定填0,不需修改
contentData.put("accessType", "0");
//
商户订单号,8-40位数字字母,不能含“-”或“_”,可以自行定制规则
contentData.put("orderId", orderId);
//
订单发送时间,格式为YYYYMMDDhhmmss,必须取当前时间,否则会报txnTime无效
contentData.put("txnTime", txnTime);
//
交易币种(境内商户一般是156 人民币)
contentData.put("currencyCode", "156");
//
交易金额,单位分,不要带小数点
contentData.put("txnAmt", txnAmt);
//
账号类型
contentData.put("accType", "01");
//
消费:交易要素卡号+验证码看业务配置(默认要短信验证码)。
Map<String,String> customerInfoMap = new HashMap<String,String>();
//
短信验证码,测试环境不会真实收到短信,固定填111111
customerInfoMap.put("smsCode", "111111");
////////////
如果商户号开通了【商户对敏感信息加密】的权限那么需要对 accNo,pin和phoneNo,cvn2,expired加密(如果这些上送的话),对敏感信息加密使用:
String accNo = AcpService.encryptData("6216261000000000018", DemoBase.encoding_UTF8); //
这里测试的时候使用的是测试卡号,正式环境请使用真实卡号
contentData.put("accNo", accNo);
contentData.put("encryptCertId",AcpService.getEncryptCertId()); //
加密证书的certId,配置在acp_sdk.properties文件 acpsdk.encryptCert.path属性下
String customerInfoStr = AcpService.getCustomerInfoWithEncrypt(customerInfoMap,"6216261000000000018",DemoBase.encoding_UTF8);
//////////
/////////
如果商户号未开通【商户对敏感信息加密】权限那么不需对敏感信息加密使用:
//contentData.put("accNo", "6216261000000000018"); //
这里测试的时候使用的是测试卡号,正式环境请使用真实卡号
//String customerInfoStr = AcpService.getCustomerInfo(customerInfoMap,"6216261000000000018",AcpService.encoding_UTF8);
////////
contentData.put("customerInfo", customerInfoStr);
// contentData.put("reqReserved", "
透传字段"); //请求方保留域,透传字段(可以实现商户自定义参数的追踪)本交易的后台通知,对本交易的交易状态查询交易、对账文件中均会原样返回,商户可以按需上传,长度为1-1024个字节
//
后台通知地址(需设置为【外网】能访问 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);
//
分期付款用法(商户自行设计分期付款展示界面):
//
修改txnSubType=03,增加instalTransInfo域
//
【测试环境】固定使用测试卡号6221558812340000,测试金额固定在100-1000元之间,分期数固定填06
//
【生产环境】支持的银行列表清单请联系银联业务运营接口人索要
// contentData.put("txnSubType", "03"); //
交易子类型 03-分期付款
// contentData.put("instalTransInfo","{numberOfInstallments=06}");//
分期付款信息域,numberOfInstallments期数
/**
对请求参数进行签名并发送http post请求,接收同步应答报文**/
Map<String, String> reqData = AcpService.sign(contentData,DemoBase.encoding_UTF8); //
报文中certId,signature的值是在signData方法中获取并自动赋值的,只要证书配置正确即可。
String requestBackUrl = SDKConfig.getConfig().getBackRequestUrl(); //
交易请求url从配置文件读取对应属性文件acp_sdk.properties中的 acpsdk.backTransUrl
Map<String, String> rspData = AcpService.post(reqData,requestBackUrl,DemoBase.encoding_UTF8); //
发送请求报文并接受同步应答(默认连接超时时间30秒,读取返回结果超时时间30秒);这里调用signData之后,调用submitUrl之前不能对submitFromData中的键值对做任何修改,如果修改会导致验签不通过
//应答码规范参考open.unionpay.com帮助中心 下载 产品接口规范 《平台接入接口规范-第5部分-附录》
if(!rspData.isEmpty()){
if(AcpService.validate(rspData, DemoBase.encoding_UTF8)){
LogUtil.writeLog("验证签名成功");
String respCode = rspData.get("respCode") ;
if(("00").equals(respCode)){
//交易已受理(不代表交易已成功),等待接收后台通知更新订单状态,也可以主动发起 查询交易确定交易状态。
//TODO
}else if(("03").equals(respCode)||
("04").equals(respCode)||
("05").equals(respCode)){
//后续需发起交易状态查询交易确定交易状态
//TODO
}else{
//其他应答码为失败请排查原因
//TODO
}
}else{
LogUtil.writeErrorLog("验证签名失败");
//TODO 检查验证签名失败的原因
}
}else{
//未返回正确的http状态
LogUtil.writeErrorLog("未获取到返回报文或返回http状态码非200");
}
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):
验证签名失败;
报文格式错(包含,必填域缺失,上送银联报文未定义的域,报文域的格式非法,交易时间超出范围);
签名失败;
超时等其他系统异常