付款交易结果异步通知
1. 接口介绍
功能简述:
商户调用了付款交易后,招行在交易处理完成时,会主动给商户发此通知。该通知包含成功、失败的情况,可使用接口中“处理结果返回码 rspCode”字段进行区分:“SUC0000”表示成功,“其他”表示失败。
约束条件:
无
正常流程:
1、 资金委托付款交易处理结束
2、 往回调地址发送通知
3、 商户响应HTTP 200
异常流程:
1、 商户提供的回调地址网络不通
2、 商户没响应HTTP 200
2. 请求地址
委托付款交易请求中商户传的结果通知地址。
例如:资金冻结完成扣款API中的noticeUrl
参数。
3. 请求报文
适用于银行主动回调商户,报文通过招行证书私钥进行签名,商户需通过招行公钥验证通知来源于招行。由银行作为发起方发起请求,商户接收请求后返回响应信息。
报文的参数名:jsonRequestData,参数值JSON格式见下表
参数名 | 类型(长度) | 必填 | 描述 | 示例 |
---|---|---|---|---|
version | String(3) | M | 固定为1.0 | 1.0 |
charset | String(8) | M | 参数编码,固定为UTF-8 | UTF-8 |
sign | String | M | 报文签名,使用招行私钥对noticeData内的数据进行签名;商户需使用招行公钥验签。 | |
signType | String | M | 签名算法,固定为RSA | RSA |
noticeData | 应答数据 | |||
dateTime | String(14) | M | 请求时间,银行处理该交易的时间。格式:yyyyMMddHHmmss | 20160623101430 |
rspCode | String | M | 处理结果返回码SUC0000 :请求处理成功其他:请求处理失败 | SUC0000 |
rspMsg | String | M | 结果描述信息 | 委托付款成功 |
noticeType | String | M | 通知类型,本接口固定为BKDB | BKDB |
noticeSerialNo | String(40) | M | 通知序号 | 201606238888888 |
branchNo | String(4) | M | 商户分行号,4位数字 | 0755 |
merchantNo | String(6) | M | 商户号,6位数字 | 002346 |
noticeUrl | String | M | 回调地址,收、退款交易填写的结果通知地址,即noticeUrl参数的内容 | http://test.52sz.co/zsPay/zsResult.php |
httpMethod | String | M | 回调方法,固定为POST | POST |
merchantSerialNo | String(32) | M | 商户交易请求流水号,全局唯一 | 2016062310143088 |
agrNo | String(32) | M | 客户签约的协议号 | 201606238888888 |
以下字段在rspCode为SUC0000时返回: | ||||
bankSerialNo | String(30) | M | 银行处理该请求的流水号 | 2016062310143099 |
amount | String(20) | M | 订单金额,以元为单位,如10.01表示10元零1分 | 10.01 |
card_type | String(2) | M | 交易卡类型02 本行借记卡 | 02 |
settleDate | String(8) | M | 银行账务日期(YYYYMMDD),用于商户与银行对账 | 20161212 |
uniqueUserID | String(30) | C | 用户ID,由身份证+姓名生成(推荐使用) | UQwanCunLbp6cl1RbDFODrhLrAa48= |
expandUserID | String(30) | C | 用户ID,由一网通ID生成(招行一网通用户的身份标识) | EUfirwdVQVKhffJmjQhMod0dS6GYY= |
相应示例:
正常json报文组织:
{ "version":"1.0", "charset":"UTF-8", "sign":"…", "signType":"RSA", "noticeData":{ "dateTime":"20160622182921", "rspCode":"SUC0000", "rspMsg":"委托付款成功", "noticeType":"BKDB", "noticeSerialNo":"201606238888888", "branchNo":"0755", "merchantNo":"002346", "noticeUrl":"http://test.52sz.co/zsPay/zsResult.php", "httpMethod":"POST", "merchantSerialNo":"2016062310143088", "bankSerialNo":"2016062310143099", "agrNo":"1234567891234568789", "amount":"10.01", "card_type":"02", "settleDate":"20161212"} }
表单组织:
<form action="请求地址" method="post" > <input type="hidden" name="jsonRequestData" value="以上json字符串" /> </form>
待验证签名字符串为:
agrNo=1234567891234568789&amount=10.01&bankSerialNo=2016062310143099&branchNo=0755&card_type=02&dateTime=20160622182921&httpMethod=POST&merchantNo=002346&merchantSerialNo=2016062310143088¬iceSerialNo=201606238888888¬iceType=BKDB¬iceUrl=http://test.52sz.co/zsPay/zsResult.php &rspCode=SUC0000&rspMsg=委托付款成功&settleDate=20161212
4. 响应报文
返回 HTTP Status Code 200,表示成功接收。否则表示未成功,未成功则银行会进行重发,重发直至响应成功或重发次数达到上限9次后停止重发。
5. 错误码
无
6. FAQ
无