支付协议签订结果通知
1. 接口介绍
功能简述:
商户调用了招行的签订支付协议API,且协议系统已处理该请求,招行会主动给商户发送成功/失败通知。
约束条件:
前端报错(例如请求参数格式错误等),招行不会主动给商户发失败通知。
正常流程:
1、 签约成功
2、 往商户签约时提供的回调地址发送通知
3、 商户响应HTTP 200
异常流程:
1、 商户提供的回调地址网络不通
2、 商户没响应HTTP 200
2. 请求地址
签订支付协议时,传送的结果通知地址noticeUrl
3. 请求报文
适用于银行主动回调商户,报文通过招行证书私钥进行签名,商户需通过招行公钥验证通知来源于招行。由银行作为发起方发起请求,商户接收请求后返回响应信息。
参数 | 类型(长度) | 必填 | 描述 | 示例 |
---|---|---|---|---|
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 | 20160622182921 |
rspCode | String(7) | M | 处理结果,SUC0000 :签约成功其他:签约失败 注意:通常只有签约成功才会发送签约结果通知, 但极少数异常情况下可能会发送 签约失败的结果通知。因此,商户收到通知报文后, 应先判断rspCode是否为SUC0000, 以确认签约是否成功。 | SUC0000 |
rspMsg | String | M | 详细信息,失败时返回的失败原因 | 签约成功 |
noticeType | String | M | 通知类型,固定为BKQY | BKQY |
noticeSerialNo | String(40) | M | 通知序号 | 201606238888888 |
branchNo | String(4) | M | 商户分行号,4位数字 | 0755 |
merchantNo | String(6) | M | 商户号,6位数字 | 002346 |
noticeUrl | String | M | 回调地址,签约请求时填写的签约结果通知地址 | http://test.52sz.co/zsPay/zsResult.php |
httpMethod | String | M | 回调方法,固定为POST | POST |
agrNo | String(32) | M | 签约请求时填写的客户协议号 | 0001283 |
noticePara | String(256) | M | 商户附加参数,原样返回商户在签约或一网通支付请求报文中传送的成功签约通知附加参数 | ABC123SDK |
userID | String(20) | M | 商户用户ID,签约请求时填写的用于标识商户用户的唯一ID | 12345 |
userPidType | String(1) | M | 用户证件类型
| 1 |
userPidHash | String(30) | M | 证件号映射的30位hash值 | 501010131010181016101010101012 |
noPwdPay | String(1) | M | 免密标识Y 表示开通免密支付N 表示不开通免密支付 | 201606238888888 |
以下字段联系招行配置控制参数后返回(默认不返回): | ||||
userRealName | String | C | 经实名认证的客户姓名,与商务合约有关, 默认不返回此字段 | AES-256对称加密后base64编码传送 |
userRealPid | String | C | 经实名认证的客户证件号, 与商务合约有关,默认不返回此字段 | AES-256对称加密后base64编码传送 |
userRealPhone | String | C | 经实名认证的客户手机号, 与商务合约有关,默认不返回此字段 | AES-256对称加密后base64编码传送 |
userRealAccNo | String | C | 经实名认证的客户银行卡号, 与商务合约有关,默认不返回此字段 | AES-256对称加密后base64编码传送 |
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", "noticeType":"BKQY", "noticeSerialNo":"201606238888888", "branchNo":"0755", "merchantNo":"002346", "noticeUrl":"https://.. ", "httpMethod":"POST", "agrNo":"0001283", "noticePara":"", "rspCode":"SUC0000", "rspMsg":"", "userID":"12345", "userPidType":"1", "userPidHash":" 501010131010181016101010101012", "noPwdPay":"N" } }
表单组织:
<form action="请求地址" method="post" > <input type="hidden" name="jsonRequestData" value="以上json字符串" /> </form>
待签名字符串(未包含支付密钥):
agrNo=000128N3&branchNo=0755&dateTime=20160622182921&httpMethod=POST&merchantNo=002346noticeParanoticePara==&noPwdPay=N=?iceSerialNo=201606238888888=?iceType=BKQY=?iceUrl=https://...=&rspCode=SUC0000=&rspMsg=&userID=12345&userPidHash=501010131010181016101010101012&userPidType=1
4. 响应报文
返回 HTTP Status Code 200,表示成功接收。否则表示未成功,未成功则银行会进行重发,重发直至响应成功或重发次数达到上限后停止重发。
5. 错误码
错误码 | 错误描述 | 解决方案 |
---|---|---|
CMBXY01 | 用户实名信息不一致 | 已实名的商户上传了实名信息,并且实名信息与银行端不一致 |
CMBMB34 | 该证件签订协议数超限,生产环境下同一个证件号默认最多支持2条不同的协议号 | 可联系招行业务接口人修改为5条,或解绑支付协议 |
CMBMB64 | 获取商户秘钥失败 | 请确认已在商户服务平台设置“支付秘钥”或联系招行技术人员解决 |
CMBMB94 | 该协议已存在 | 请用新的协议号进行签约。 注:一个协议号如果已分配给某个客户且已签约成功,即使关闭协议,该协议号也不能再分配给其他客户 |
CMBMB97 | 请求参数错误 | 根据提示信息中括号里的内容,修改请求参数。 如:请求参数错误(商户交易日期),检查”商户交易日期”字段的内容是否正确 |
6. FAQ
无