银联在线网关支付，快速接入指南
银联在线支付网关是中国银联联合各商业银行为持卡人提供的集成化、综合性互联网支付工具，主要支持输入卡号付款、用户登录支付、网银支付、迷你付（IC卡支付）等多种支付方式，为持卡人提供境内外网上购物支付服务。网关支付产品主要适用于持卡人在商户网站B2C购物支付场景，持卡人通过点击银联在线支付图标，并跳转银联页面完成支付信息录入，最终完成支付。
特色
安全支付
采用多重安全防控技术，强大的风险监控系统实时拦截交易。
完备的风险处置和化解机制，维护参与各方的利益。
快捷支付
持卡人无需开通网银即可畅享网上支付服务，商户可以直接受理带有银联Logo的约40多亿张银联卡。
全球支付
银联跨境网上支付服务已经覆盖全球主要国家和地区，国内外银联卡均可使用，境外网上受理商户免收货币转换费，持卡人足不出户即可“轻点鼠标，网购全球”。
优惠乐享
银联在线支付与240多家银行及万余家商户持续不断的开展优惠活动，抽奖、立减、返现、返券、送话费、送积分等奖励形式不一而足，让持卡人乐享网上支付新生活。
下面将为大家展示在线网关支付有哪些API接口，如何快速接入在线网关支付。介绍如何从零开始，使用银联开放服务平台服务端SDK快速接入网关支付产品，完成与银联对接的部分。
注意：以下的代码示例和Demo是用来阐述API基本使用方法的，针对大部分基本业务场景。供商户参考，特殊情况请按照进阶功能扩展，确保符合实际业务需求。
API接口：消费接口、消费撤销接口、退货接口、交易状态查询接口、银联加密公钥更新查询接口、预授权接口、预授权撤销、预授权完成、预授权完成撤销、文件传输接口（对账文件下载）。您可以点击在线网关支付的API列表查看更多详细信息。
第一步：申请入网
您有2种方式可以选择：
1.在银联官网注册：
您可以点击页面中的【我要入网】，发起自助签约申请。
详见入网申请流程
2.联系服务商：
见服务商介绍
第二步：申请证书
开发者调用接口前需要先获取三个证书：签名证书、敏感信息加密证书、验签证书。
● 签名证书
- 证书用途
商户或机构对报文中出现签名域（signature）之外的所有数据元采用key=value的形式按照名称排序， 然后以&作为连接符拼接成待签名串。其次，对待签名串使用SHA-256算法做摘要， 再使用银联颁发给商户的签名私钥证书中的私钥对摘要做签名操作（签名时算法选择 SHA-256）。 最后，对签名做Base64编码，将编码后的签名串放在签名（signature）表单域里和 其他表单域一起通过HTTP Post的方式传输给银联全渠道支付平台。
- 如何获取
测试环境签名证书接从开发包中目录assets下获取。
生产环境签名证书获取方式：入网流程走完后，银联业务运营中心会发送入网通知邮件给申请表中的联系人邮箱， 请参考邮件中《证书下载、导出及上传流程》文档进行下载， 下载时需要的证书序列号、授权码会在邮件正文或者附件中给出。
● 验签证书
- 证书用途
商户或机构对报文中出现签名域（signature）之外的所有数据元采用key=value的形式按照名称升序排序，然后以&作为连接符拼接成待签名串。 其次，对待签名串使用 SHA-256算法做摘要，再使用商户入网时银联提供的验签公钥证书中的公钥对摘要和报文中的签名信息做签名验证操作。
- 如何获取
验签证书直接从开发包中目录assets下获取。
第三步：集成并配置SDK
为了帮助开发者调用开放接口，我们提供了开放平台服务端SDK，包含JAVA、PHP和.NET三语言版本， 封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。
网关支付
网关支付产品包含两类API，在设置测试、生产地址时请注意前后台交易地址差异。
前台交易API： 消费交易为前台交易，需要跳转到银联支付页面进行支付。需要从前端页面以Form表单的形式发起请求，浏览器会自动跳转至银联的相关页面（一般是支付或开通页面），用户在该页面完成相关业务操作后再回跳到商户指定页面。
后台交易API： 直接从服务端发起HTTP请求，商户网站按照接口发送到银联后台即可，不跳转到银联页面，除消费交易以外的其他交易均属于后台交易。
调用流程
如上图所示，持卡人在商户的网站下单后，商户系统按照 消费API的参数规范生成订单数据，然后在前端页面通过Form表单的形式请求到银联前台地址，自动将页面跳转至银联网关页面。
持卡人在银联页面完成支付后，会根据商户在消费API中传入的前台通知地址frontUrl在持卡人主动点击“返回商户”时跳转回商户页面，同时在应答报文中附带上支付结果参数，详细通知参数见 消费API的前台通知。
同时，银联还会根据 原始消费API中传入的异步通知地址backUrl，通过POST请求的形式将支付结果作为参数通知到商户系统，详情见后台通知（异步应答）。
除了正向支付流程外，银联也提供交易状态查询、退货以及对账等配套API。
特别注意
● 由于前台通知需要持卡人主动点击“返回商户”，存在不可靠性，前台通知只能作为商户支付结果页的入口，最终支付结果必须以交易状态查询接口返回为准，不能仅依赖前台通知。
● 消费的交易状态查询收到respCode=00同时origRespCode=00时则表示被查询交易成功，其他表示处理中，非成功的前台消费交易都可以继续跳转过来重新支付。
● 商户系统接收到前台通知或后台通知以后，必须通过验签（验证通知中的signature参数）来确保支付通知是由银联发送的。验签方法参考通知。
● 接收到前台通知或后台通知并验签通过后，根据通知中的orderId、txnTime、merId发起交易查询请求查询交易结果。
3.前台通知应答码
前台通知表示成功的应答码是00或A6，只有支付成功时才会发送前台通知，交易失败时（比如余额不足时）不发送。
后台通知应答码
后台通知表示成功的应答码是00或A6，网关支付只有交易成功全渠道才会发后台通知给商户；
其他后台资金类交易，如退货、消费撤销，全渠道系统均会给请求方后台通知，请求方也必须实现接收后台通知。
使用SDK快速接入
网关支付com.unionpay.acp.demo.consume.Form_6_2_FrontConsume：
|
protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { resp.setContentType(“text/html; charset=”+ DemoBase.encoding); //前台页面传过来的 String merId = req.getParameter(“merId”); String txnAmt = req.getParameter(“txnAmt”); Map<String, String> requestData = new HashMap<String, String>(); /***银联全渠道系统，产品参数，除了encoding自行选择外其他不需修改***/ requestData.put(“version”, DemoBase.version); //版本号，全渠道默认值 requestData.put(“encoding”, DemoBase.encoding); //字符集编码，可以使用UTF-8,GBK两种方式 requestData.put(“signMethod”, SDKConfig.getConfig().getSignMethod()); //签名方法 requestData.put(“txnType”, “01”); //交易类型 ，01：消费 requestData.put(“txnSubType”, “01”); //交易子类型， 01：自助消费 requestData.put(“bizType”, “000201”); //业务类型，B2C网关支付，手机wap支付 requestData.put(“channelType”, “07”); //渠道类型，这个字段区分B2C网关支付和手机wap支付；07：PC,平板 08：手机 /***商户接入参数***/ requestData.put(“merId”, merId); //商户号码，请改成自己申请的正式商户号或者open上注册得来的777测试商户号 requestData.put(“accessType”, “0”); //接入类型，0：直连商户 requestData.put(“orderId”,DemoBase.getOrderId()); //商户订单号，8-40位数字字母，不能含“-”或“_”，可以自行定制规则 requestData.put(“txnTime”, DemoBase.getCurrentTime()); //订单发送时间，取系统时间，格式为YYYYMMDDhhmmss，必须取当前时间，否则会报txnTime无效 requestData.put(“currencyCode”, “156”); //交易币种（境内商户一般是156 人民币） requestData.put(“txnAmt”, txnAmt); //交易金额，单位分，不要带小数点 //requestData.put(“reqReserved”, “透传字段”); //请求方保留域，如需使用请启用即可；透传字段（可以实现商户自定义参数的追踪）本交易的后台通知,对本交易的交易状态查询交易、对账文件中均会原样返回，商户可以按需上传，长度为1-1024个字节。出现&={}[]符号时可能导致查询接口应答报文解析失败，建议尽量只传字母数字并使用|分割，或者可以最外层做一次base64编码(base64编码之后出现的等号不会导致解析失败可以不用管)。 //前台通知地址 （需设置为外网能访问 http https均可），支付成功后的页面 点击“返回商户”按钮的时候将异步通知报文post到该地址 //如果想要实现过几秒中自动跳转回商户页面权限，需联系银联业务申请开通自动返回商户权限 //异步通知参数详见open.unionpay.com帮助中心 下载 产品接口规范 网关支付产品接口规范 消费交易 商户通知 requestData.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 在后台通知处理程序验证签名之前需要编写逻辑将这些字段去掉再验签，否则将会验签失败 requestData.put(“backUrl”, DemoBase.backUrl); // 订单超时时间。 // 超过此时间后，除网银交易外，其他交易银联系统会拒绝受理，提示超时。 跳转银行网银交易如果超时后交易成功，会自动退款，大约5个工作日金额返还到持卡人账户。 // 此时间建议取支付时的北京时间加15分钟。 // 超过超时时间调查询接口应答origRespCode不是A6或者00的就可以判断为失败。 requestData.put(“payTimeout”, new SimpleDateFormat(“yyyyMMddHHmmss”).format(new Date().getTime() + 15 * 60 * 1000)); ////////////////////////////////////////////////// // // 报文中特殊用法请查看 PCwap网关跳转支付特殊用法.txt // ////////////////////////////////////////////////// /**请求参数设置完毕，以下对请求参数进行签名并生成html表单，将表单写入浏览器跳转打开银联页面**/ Map<String, String> submitFromData = AcpService.sign(requestData,DemoBase.encoding); //报文中certId,signature的值是在signData方法中获取并自动赋值的，只要证书配置正确即可。 String requestFrontUrl = SDKConfig.getConfig().getFrontRequestUrl(); //获取请求银联的前台地址：对应属性文件acp_sdk.properties文件中的acpsdk.frontTransUrl String html = AcpService.createAutoFormHtml(requestFrontUrl, submitFromData,DemoBase.encoding); //生成自动跳转的Html表单 LogUtil.writeLog(“打印请求HTML，此为请求报文，为联调排查问题的依据：”+html); //将生成的html写到浏览器中完成自动跳转打开银联支付页面；这里调用signData之后，将html写到浏览器跳转到银联页面之前均不能对html中的表单项的名称和值进行修改，如果修改会导致验签不通过 resp.getWriter().write(html); } |
在线网关支付API的关键入参、关键通知参数等更多详细信息可点击链接：https://open.unionpay.com/tjweb/acproduct/list?apiservId=448