用于商户接受持卡人委托,在通过持卡人卡片和身份信息校验或绑定的前提下,发起的扣款交易。
POST
https://gateway.95516.com/gateway/api/backTransReq.do
https://gateway.test.95516.com/gateway/api/backTransReq.do
中文名称 | 英文名称 | 域类型 | 默认值 | 请求要求 | 备注 | |||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
版本号 | version | NS5 | 无 | M-必填 |
固定填写5.1.0 |
|||||||||||||||||||||||||||||||||||||||||||||||||||
编码方式 | encoding | ANS1..20 | UTF-8 | M-必填 | 默认取值:UTF-8 | |||||||||||||||||||||||||||||||||||||||||||||||||||
证书ID | certId | N1..128 | 无 | C-按条件必填 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
签名 | signature | ANS1..1024 | 0 | M-必填 | 填写对报文摘要的签名 | |||||||||||||||||||||||||||||||||||||||||||||||||||
签名方法 | signMethod | N2 | 无 | M-必填 |
非对称签名: 01:签名采用RSA算法,使用SHA-256散列算法配合;敏感信息加解密采用RSA算法 21:签名采用SM2算法,使用SM3散列算法配合;敏感信息加解密采用SM2算法 散列验证算法: 11:支持散列方式验证SHA-256 12:支持散列方式验证SM3
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
交易类型 | txnType | N2 | 无 | M-必填 | 取值:11 | |||||||||||||||||||||||||||||||||||||||||||||||||||
交易子类 | txnSubType | N2 | 无 | M-必填 |
取值:03 |
|||||||||||||||||||||||||||||||||||||||||||||||||||
产品类型 | bizType | N6 | 无 | M-必填 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
渠道类型 | channelType | N2 | 无 | M-必填 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
后台通知地址 | backUrl | ANS1..256 | 无 | M-必填 |
交易后台返回商户结果时使用,如上送,则发送商户后台交易结果通知,如需通过专线通知,需要在通知地址前面加上前缀:专线的首字母加竖线ZX| |
|||||||||||||||||||||||||||||||||||||||||||||||||||
接入类型 | accessType | N1 | 无 | M-必填 |
0:商户直连接入 1:收单机构接入 2:平台商户接入 |
|||||||||||||||||||||||||||||||||||||||||||||||||||
收单机构代码 | acqInsCode | AN8..11 | 无 | C-按条件必填 | 接入类型为收单机构接入时需返回 | |||||||||||||||||||||||||||||||||||||||||||||||||||
商户类别 | merCatCode | N4 | 无 | C-按条件必填 | 接入类型为收单机构接入时需上送 | |||||||||||||||||||||||||||||||||||||||||||||||||||
商户代码 | merId | AN15 | 无 | M-必填 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
商户名称 | merName | ANS1..40 | 无 | C-按条件必填 | 接入类型为收单机构接入时需上送 | |||||||||||||||||||||||||||||||||||||||||||||||||||
商户英文名称 | merEnName | ANS40 | C-按条件必填 | 查看详情 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
商户简称 | merAbbr | ANS1..8 | 无 | C-按条件必填 | 接入类型为收单机构接入时需上送 | |||||||||||||||||||||||||||||||||||||||||||||||||||
二级商户代码 | subMerId | AN5..15 | 无 | C-按条件必填 | 商户类型为平台类商户接入时必须上送 | |||||||||||||||||||||||||||||||||||||||||||||||||||
二级商户名称 | subMerName | ANS1..40 | 无 | C-按条件必填 | 商户类型为平台类商户接入时必须上送 | |||||||||||||||||||||||||||||||||||||||||||||||||||
二级商户简称 | subMerAbbr | ANS1…16 | 无 | C-按条件必填 | 商户类型为平台类商户接入时必须上送 | |||||||||||||||||||||||||||||||||||||||||||||||||||
商户订单号 | orderId | AN8..40 | 无 | M-必填 |
商户订单号,不能含“-”或“_”; 商户自定义,同一交易日期内不可重复; 商户代码merId、商户订单号orderId、订单发送时间txnTime三要素唯一确定一笔交易。 |
|||||||||||||||||||||||||||||||||||||||||||||||||||
订单发送时间 | txnTime | YYYYMMDDhhmmss | 无 | M-必填 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
账号 | accNo | AN1..1024 | 无 | M-必填 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
交易金额 | txnAmt | N1..12 | 无 | M-必填 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
交易币种 | currencyCode | AN3 | 无 | M-必填 | 默认为156 | |||||||||||||||||||||||||||||||||||||||||||||||||||
银行卡验证信息及身份信息 | customerInfo | ANS1..1024 | 无 | O-选填 | 查看详情 | |||||||||||||||||||||||||||||||||||||||||||||||||||
代收款项 | billType | ANS2 | 无 | M-必填 |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
用户号码 | billNo | ANS1..64 | 无 | M-必填 |
账单查询/支付类交易中填写具体账单号码 用法一:账单查询/支付类交易中网上缴税用法,填写纳税人编码 用法二:账单查询/支付类交易中信用卡还款用法,填写信用卡卡号 |
|||||||||||||||||||||||||||||||||||||||||||||||||||
持卡人IP | customerIp | NS7..40 | 无 | O-选填 | 有IP防钓鱼要求的商户上送 | |||||||||||||||||||||||||||||||||||||||||||||||||||
账单周期 | billPeriod | ANS17 | 无 | O-选填 | 格式为:yyyyMMdd-yyyyMMdd | |||||||||||||||||||||||||||||||||||||||||||||||||||
请求方保留域 | reqReserved | ANS1..1024 | 无 | O-选填 | 商户自定义保留域,交易应答时会原样返回 | |||||||||||||||||||||||||||||||||||||||||||||||||||
保留域 | reserved | ANS1..2048 | 无 | O-选填 | 查看详情 | |||||||||||||||||||||||||||||||||||||||||||||||||||
风控信息域 | riskRateInfo | ANS 1..2048 | 无 | O-选填 | 查看详情 | |||||||||||||||||||||||||||||||||||||||||||||||||||
加密证书ID | encryptCertId | N1..128 | 无 | C-按条件必填 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
终端号 | termId | ANS8 | 无 | O-选填 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
分账域 | accSplitData | ANS1..512 | 无 | O-选填 | 查看详情 | |||||||||||||||||||||||||||||||||||||||||||||||||||
控制规则 | ctrlRule | N32 | 无 | O-选填 |
第五位取值为1时表示不返signPubKeyCert字段 |
|||||||||||||||||||||||||||||||||||||||||||||||||||
账户验证关联交易主键 | verfPriKey | ANS42 | O-选填 |
用于上送前序关联支付验证交易主键信息
|
中文名称 | 英文名称 | 域类型 | 默认值 | 请求要求 | 备注 | |
---|---|---|---|---|---|---|
版本号 | version | NS5 | 无 | R-需要返回 | ||
编码方式 | encoding | ANS1..20 | UTF-8 | R-需要返回 | ||
签名 | signature | ANS1..1024 | 0 | M-必填 | ||
签名方法 | signMethod | N2 | 无 | M-必填 | ||
交易类型 | txnType | N2 | 无 | R-需要返回 | ||
交易子类 | txnSubType | N2 | 无 | R-需要返回 | ||
产品类型 | 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-需要返回 | ||
账号 | accNo | AN1..1024 | 无 | C-按条件必填 | ||
交易金额 | txnAmt | N1..12 | 无 | R-需要返回 | ||
交易币种 | currencyCode | AN3 | 无 | R-需要返回 | 默认为156 | |
请求方保留域 | reqReserved | ANS1..1024 | 无 | R-需要返回 | ||
保留域 | reserved | ANS1..2048 | 无 | O-选填 | 查看详情 | |
查询流水号 | queryId | AN20..21 | 无 | M-必填 | ||
应答码 | respCode | AN2 | 无 | M-必填 | ||
应答信息 | respMsg | ANS1..256 | 无 | M-必填 | ||
签名公钥证书 | signPubKeyCert | AN1..2048 | 无 | C-按条件必填 | 此域填写银联签名公钥证书,使用RSA签名方式时,默认返回,如果ctrlRule第五位为1时,不返。 |
中文名称 | 英文名称 | 域类型 | 默认值 | 请求要求 | 备注 | |
---|---|---|---|---|---|---|
版本号 | version | NS5 | 无 | R-需要返回 | ||
编码方式 | encoding | ANS1..20 | UTF-8 | R-需要返回 | ||
签名 | signature | ANS1..1024 | 0 | M-必填 | ||
签名方法 | signMethod | N2 | 无 | M-必填 | ||
交易类型 | txnType | N2 | 无 | R-需要返回 | ||
交易子类 | txnSubType | N2 | 无 | R-需要返回 | ||
产品类型 | 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-需要返回 | ||
账号 | accNo | AN1..1024 | 无 | C-按条件必填 | ||
交易金额 | txnAmt | N1..12 | 无 | R-需要返回 | ||
交易币种 | currencyCode | AN3 | 无 | R-需要返回 | 默认为156 | |
请求方保留域 | reqReserved | ANS1..1024 | 无 | R-需要返回 | ||
保留域 | reserved | ANS1..2048 | 无 | O-选填 | 查看详情 | |
交易查询流水号 | queryId | AN20..21 | 无 | M-必填 | 由银联返回,用于在后续类交易中唯一标识一笔交易 |
|
应答码 | respCode | AN2 | 无 | M-必填 | ||
应答信息 | respMsg | ANS1..256 | 无 | M-必填 | ||
清算金额 | settleAmt | N1..12 | 无 | M-必填 | ||
清算日期 | settleDate | MMDD | 无 | M-必填 | ||
清算币种 | settleCurrencyCode | AN3 | 无 | M-必填 | ||
系统跟踪号 | traceNo | N6 | 无 | M-必填 | ||
交易传输时间 | traceTime | MMDDhhmmss | 无 | M-必填 | ||
兑换日期 | exchangeDate | MMDD | 无 | C-按条件必填 | 交易成功,交易币种和清算币种不一致的时候返回 | |
清算汇率 | exchangeRate | N8 | 无 | C-按条件必填 | 交易成功,交易币种和清算币种不一致的时候返回 | |
支付卡类型 | payCardType | N2 | 无 | C-按条件必填 | 根据商户配置返回 | |
签名公钥证书 | signPubKeyCert | AN1..2048 | 无 | C-按条件必填 | 此域填写银联签名公钥证书,使用RSA签名方式时,默认返回,如果ctrlRule第五位为1时,不返。 |
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()); //签名方法 目前只支持01-RSA方式证书加密
contentData.put("txnType", "11"); //交易类型 11-代收
contentData.put("txnSubType", "00"); //交易子类型 默认00
contentData.put("bizType", "000501"); //业务类型 代收产品
contentData.put("channelType", "07"); //渠道类型07-PC
/***商户接入参数***/
contentData.put("merId", merId); //商户号码(商户号码777290058110097仅做为测试调通交易使用,该商户号配置了需要对敏感信息加密)测试时请改成自己申请的商户号,【自己注册的测试777开头的商户号不支持代收产品】
contentData.put("accessType", "0"); //接入类型,商户接入固定填0,不需修改
contentData.put("orderId", orderId); //商户订单号,8-40位数字字母,不能含“-”或“_”,可以自行定制规则
contentData.put("txnTime", txnTime); //订单发送时间,格式为YYYYMMDDhhmmss,必须取当前时间,否则会报txnTime无效
contentData.put("currencyCode", "156"); //交易币种(境内商户一般是156 人民币)
contentData.put("txnAmt", txnAmt); //交易金额,单位分,不要带小数点
contentData.put("accType", "01"); //账号类型
Map<String,String> customerInfoMap = new HashMap<String,String>();
//【代收的customerInfo送什么验证要素是配置到银联后台到商户号上的,这些验证要素可以在商户的《全渠道入网申请表》中找到,也可以请咨询您的业务人员或者银联业务运营接口人】
//以下上送要素是参考《测试商户号777290058110097代收、实名认证交易必送验证要素配置说明.txt》贷记卡(实名认证交易-后台)部分
customerInfoMap.put("certifTp", "01");//证件类型
customerInfoMap.put("certifId", "341126197709218366");//证件号码
customerInfoMap.put("customerNm", "全渠道");//姓名
customerInfoMap.put("phoneNo", "13552535506"); //手机号
//customerInfoMap.put("cvn2", "123"); //卡背面的cvn2三位数字
//customerInfoMap.put("expired", "1711"); //有效期 年在前月在后
/////////不对敏感信息加密使用:
//contentData.put("accNo", "6216261000000000018"); //这里测试的时候使用的是测试卡号,正式环境请使用真实卡号
//String customerInfoStr = AcpService.getCustomerInfo(customerInfoMap,null,DemoBase.encoding_UTF8);
////////
//////////如果商户号开通了 商户对敏感信息加密的权限那么,需要对 卡号accNo,pin和phoneNo,cvn2,expired加密(如果这些上送的话),对敏感信息加密使用:
contentData.put("encryptCertId",AcpService.getEncryptCertId());
String accNo = AcpService.encryptData("6216261000000000018", DemoBase.encoding);
contentData.put("accNo", accNo);
String customerInfoStr = AcpService.getCustomerInfoWithEncrypt(customerInfoMap,"6216261000000000018",DemoBase.encoding);
//////////
contentData.put("customerInfo", customerInfoStr);
//后台通知地址(需设置为【外网】能访问 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);
// 请求方保留域,
// 透传字段,查询、通知、对账文件中均会原样出现,如有需要请启用并修改自己希望透传的数据。
// 出现部分特殊字符时可能影响解析,请按下面建议的方式填写:
// 1. 如果能确定内容不会出现&={}[]"'等符号时,可以直接填写数据,建议的方法如下。
//contentData.put("reqReserved", "透传信息1|透传信息2|透传信息3");
// 2. 内容可能出现&={}[]"'符号时:
// 1) 如果需要对账文件里能显示,可将字符替换成全角&={}【】“‘字符(自己写代码,此处不演示);
// 2) 如果对账文件没有显示要求,可做一下base64(如下)。
// 注意控制数据长度,实际传输的数据长度不能超过1024位。
// 查询、通知等接口解析时使用new String(Base64.decodeBase64(reqReserved), DemoBase.encoding);解base64后再对数据做后续解析。
//contentData.put("reqReserved", Base64.encodeBase64String("任意格式的信息都可以".toString().getBytes(DemoBase.encoding)));
/**对请求参数进行签名并发送http post请求,接收同步应答报文**/
Map<String, String> reqData = AcpService.sign(contentData,DemoBase.encoding); //报文中certId,signature的值是在signData方法中获取并自动赋值的,只要证书配置正确即可。
String requestBackUrl = SDKConfig.getConfig().getBackRequestUrl(); //交易请求url从配置文件读取对应属性文件acp_sdk.properties中的 acpsdk.backTransUrl
Map<String, String> rspData = AcpService.post(reqData,requestBackUrl,DemoBase.encoding); //发送请求报文并接受同步应答(默认连接超时时间30秒,读取返回结果超时时间30秒);这里调用signData之后,调用submitUrl之前不能对submitFromData中的键值对做任何修改,如果修改会导致验签不通过
/**对应答码的处理,请根据您的业务逻辑来编写程序,以下应答码处理逻辑仅供参考------------->**/
//应答码规范参考open.unionpay.com帮助中心 下载 产品接口规范 《平台接入接口规范-第5部分-附录
if(!rspData.isEmpty()){
if(AcpService.validate(rspData, DemoBase.encoding)){
LogUtil.writeLog("验证签名成功");
String respCode = rspData.get("respCode") ;
if(("00").equals(respCode)){
//交易已受理(不代表交易已成功),等待接收后台通知更新订单状态,也可以主动发起 查询交易确定交易状态。
//TODO
//如果是配置了敏感信息加密,如果需要获取卡号的铭文,可以按以下方法解密卡号
//String accNo1 = resmap.get("accNo");
//String accNo2 = AcpService.decryptData(accNo1, "UTF-8"); //解密卡号使用的证书是商户签名私钥证书acpsdk.signCert.path
//LogUtil.writeLog("解密后的卡号:"+accNo2);
}else if(("03").equals(respCode)||
("04").equals(respCode)||
("05").equals(respCode)){
//后续需发起交易状态查询交易确定交易状态
//TODO
}else{
//其他应答码为失败请排查原因
//TODO
}
}else{
LogUtil.writeErrorLog("验证签名失败");
//TODO 检查验证签名失败的原因
}
}else{
//未返回正确的http状态
LogUtil.writeErrorLog("未获取到返回报文或返回http状态码非200");
}
String reqMessage = DemoBase.genHtmlResult(reqData);
String rspMessage = DemoBase.genHtmlResult(rspData);
resp.getWriter().write("请求报文:<br/>"+reqMessage+"<br/>" + "应答报文:</br>"+rspMessage+"");
}
1. 不返回报文体的情况:
版本号,交易类型、子类,签名方法,签名值等关键域未上送,返回“Invalid request.”; 交易类型和请求地址校验有误,返回“Invalid request URI.”
2. 返回全部的请求报文,附加应答码和应答描述(包括的应答码有:01、02、03、10、11、32):
验证签名失败;
报文格式错(包含,必填域缺失,上送银联报文未定义的域,报文域的格式非法,交易时间超出范围);
签名失败;
超时等其他系统异常