Java开发对接招行一网通支付功能的总结

									招商银行一网通支付JAVA开发

最近对接了招行一网通的支付功能,记录一下.
一.一网通支付方式主要分为6种:APP支付,H5支付,PC扫码支付,二维码支付,小程序支付,Apple Pay支付.本次开发主要针对H5支付和PC扫码支付.
二.测试开发准备工作:
1．对接分行工作人员开通测试环境账号(对申请方资质需要审核);
2．分行号,商户号,商户秘钥,签约功能进行配置(https://121.15.180.92:60106/cmb-mser);
3．验证码查询(签约功能需要;但可不比使用此功能,支付API支持自动签约);
4．API文档(http://openhome.cmbchina.com/pay/Default.aspx)
三.开发测试流程(以H5为例)
1．场景介绍了解:
（1） 文档地址: http://openhome.cmbchina.com/pay/H5Pay/AppIntro/SceneIntro.aspx
用户首次进行一网通支付流程
步骤1：用户在商户H5页面中选择商品下单、确认购买，进入支付环节，选择一网通支付，用户点击确认支付，如图1；
步骤2：用户输入手机号登录一网通用户，点击下一步，如图2；
步骤3：若用户未注册一网通用户，则点击添卡支付，如图3；
步骤4：用户填写银行卡信息：卡号、姓名、身份证号，如图4；
步骤5：若用户添加他行卡，需填写手机号和短信验证码，添加本行卡不需要这步，如图5；
步骤6：设置一网通支付密码，并确认，如图6；
步骤7：显示支付结果，如图7。
（2）交互时序图(业务流程)
商户系统和一网通支付系统主要交互说明：
步骤1：用户在商户端页面选择商品，提交订单，选择一网通支付。
步骤2：商户后台收到支付订单，调用一网通支付接口。参见一网通支付API
步骤3：系统校验成功后，引导用户进行登录。
步骤4：用户完成登陆后，进入支付详情页，页面展示商户名称、交易单号、支付账户、订单金额等信息，用户点击“立即支付”后，完成支付。
步骤5：商户前端收到成功支付结果通知。参见成功支付结果前端通知API
步骤6：商户后台收到成功支付结果通知。参见成功支付结果通知API
步骤7：商户后台收到成功签约结果通知。参见成功签约结果通知API
步骤8：商户后台查询支付结果。参见查询单笔订单API
步骤9：商户后台查询签约结果。参见查询协议API

四.开发工作:
1．用户下单->商户生成订单的工作由业务需求自行调整.
2．一网通支付API所需报文数据准备完成,直接调用对应API(http://121.15.180.66:801/netpayment/BaseHttp.dll?MB_EUserPay)
特殊参数说明:
2.1
（1）payNoticeUrl和payNoticePara:这2个参数用于接收支付成功之后招行回调过来的落地数据.采用POST请求,后台接口可直接用”String data = request.getParameter(“jsonRequestData”); ”获取返回数据jsonRequestData.
payNoticePara根据商户自定义需求,可将部分需携带信息用此字段封装,回随成功支付回调API一并返回回调地址payNoticeUrl.注意:payNoticePara的参数需用”|”来区分,组合不同参数,但不可有特殊字符.
(2)关于支付API自动签约功能(此方法可不必单独调用签约API).
需在用户首次使用一网通支付时,由商户生成agrNo(客户协议号), merchantSerialNo(协议开通请求流水号)以及signNoticeUrl(签约成功结果回调).其中,后两个参数在首次支付签约时必传,后续支付可省略.注意:客户和客户协议号在商户数据库需做到一一对应.一个一网通账户最多有2个协议号.
(3)returnUrl: 返回商户地址，支付成功页面、支付失败页面上“返回商户”按钮跳转地址.需要注意,此地址由用户点击”返回商户”按钮或10秒等待结束跳转.招行使用POST方式来请求该页面,需要注意前端路由的Nginx是否阻止了POST方式请求页面的问题;同时,returnUrl的地址不可带有”#”号这些特殊符号,招行会默认截取”#”号之后的数据,导致跳转地址不正确.
(4)关于支付完成后返回页面的数据展示问题:一定要以”成功支付结果通知API”的回调报文数据为准,不可以使用”支付成功前端通知API”作为是否支付成功的判定标准.一般推荐在payNoticeUrl的接口中获取返回报文成功校验后同步更新数据库订单信息,由返回页面调用接口查询本地数据库的订单信息再做展示.(payNoticeUrl的回调报文是落地数据)
3．后台业务逻辑部分:
（1）签名:签名和验签对于支付功能来讲是非常重要的工作,能够有效防止非法数据侵入,确保数据有效性,合法性.关于签名和验签,可以详细参考招行一网通文档代码示例部分(http://openhome.cmbchina.com/pay/H5Pay/APIList/CodeExamples.aspx)
需要注意的是,待签名的数据需要先进行字典排序,Java可以使用TreeMap自动排序,再进行数据拼接和加密处理.
签名规范见文档(http://openhome.cmbchina.com/pay/H5Pay/APIList/SignatureCheck.aspx)
（2）成功支付结果通知回调接口:每笔支付成功的订单,银行均会即时POST请求在支付API中填写的payNoticeUrl地址.所以当未接收到请求时,可以先检查是否被系统拦截(一般系统都会存在认证拦截).当收到此回调请求时,需进行数据的验签工作,主要是确保该数据来自于招行.验签代码在上一点的地址中可以查询.验签时,当第一次验签失败,推荐重复获取招行公钥再次进行验签,防止公钥失效或变更导致的错误验证.
（3）验签时,需要获取招行公钥,通过SHA1WithRSA算法进行加密校验.所以,公钥接口需在后台进行调用.建议用户使用定时任务,自动定时获取公钥数据并存入数据库,就无需频繁调用API.(我是设置每天早上6点获取一次).SpringCloud可以使用@Schedule注释,快捷方便.当然,若第一次验签失败,需要重新调用公钥接口,防止公钥变更导致的错误.
（4）验证成功,需即时返回响应报文:返回 HTTP Status Code 200，表示成功接收。否则表示未成功，未成功则银行会进行重发，重发直至响应成功或重发次数达到上限9次后停止重发。很简单:直接response.setStatus(200)就可以了.
推荐验签时将支付请求发起时存入数据库的订单数据和回调报文的数据做部分匹配(例如:支付金额等),降低数据存储错误.
（5）验签成功后,根据需求进行订单数据的更新及后续业务逻辑处理.自此,一个完整的支付流程基本结束.
4．关于PC扫码支付,基本流程与H5支付一致,唯一需要注意的坑,就是PC扫码多了一个productDesc(商品描述),文档没说必传,但是实际开发中发现,此字段属于必填项,否则会发生签名错误的问题.
5．关于额外的自定义请求API的报文数据,例如expireTimeSpan(订单过期时间跨度),encrypData(加密数据)等各位再做文档研究.
6．前端部分:因为开启支付功能,基本都是由用户在页面点击”支付”发起,所以发起一网通支付API请求时,我的流程如下:前端封装支付必要数据(dateTime,agrNo,orderNo等),先调后台接口进行签名,再返回Map集合数据交由前端页面,通过form表单的方式进行提交.一定注意的是form表单,原因有2点:
（1）Ajax模拟post请求会导致跨域,一个是无法正确获取数据,二是跨域容易触发银行风控
（2）其实form表单成功提交后,整个的支付界面都是跳转至招行的页面来操作的,只是在用户完成支付操作后,由银行进行数据回调请求而已.
7．最后分享几点开发当中的小问题:
（1）一个是注意开发期间是否处于招行系统维护,此时会有白名单的限制,需要提供公网ip地址加入白名单才可以访问API,特别麻烦.
（2）开发测试是使用的测试环境(上述API地址均为测试地址),所以会有很多限制:测试卡限额,支付请求响应过慢(被限制了网速)等等问题.大家耐心一点就好^_
(3) 开发时,有部分通用数据(例如:私钥,公钥请求地址,订单查询地址,退款地址,商户号,分行号等基础信息,建议写入配置文件读取,尽量不要在代码中写死)
(4) 可以考虑对存入数据库的敏感信息做脱敏处理