周期扣款

收款

1. 接口介绍

功能简述:

本接口用于周期扣款商户对已签订支付协议的用户进行收款,目前仅支持对协议绑定银行卡进行扣款,同步返回扣款结果(成功、失败、未知/处理中)。该接口支持“招行借记卡/信用卡、他行卡”的扣款。

约束条件:

1、 用户已签订周期扣款支付协议
2、 商户在招行系统开通“支持免密支付(代收)”模式

正常流程:

1、 报文合性校验
2、 报文参数校验
3、 同步返回请求处理成功、失败或未知

异常流程:

1、 请求源IP不在IP白单中
2、 报文验签失败
3、 报文参数非法
4、 限额超限
5、 用户已关闭免密支付功能

2. 请求地址

测试环境URL:

https://cmbchinab2b.bas.cmburl.cn/CmbBank_B2B/UI/NetPay/DoBusiness.ashx

生产环境URL:

https://b2b.cmbchina.com/CmbBank_B2B/UI/NetPay/DoBusiness.ashx

3. 请求报文

请求报文参数类型(长度)必填描述示例
charsetString(8)M编码格式,固定为UTF-8UTF-8
jsonRequestDataStringMjson格式的请求参数,详见jsonRequestData定义

jsonRequestData参数定义

参数名类型(长度)必填描述示例
versionString(3)M固定为1.01.0
signStringM使用商户支付密钥对reqData内的数据进行签名
signTypeStringM固定为SHA-256SHA-256
reqData请求数据


dateTimeString(14)M请求时间,商户发起该请求的时间,精确到秒。
格式:yyyyMMddHHmmss
20160623101430
txCodeStringM交易码,固定为CMSKCMSK
branchNoString(4)M商户分行号,4位数字0755
merchantNoString(6)M商户号,6位数字002346
merchantSerialNoString(32)M商户交易请求流水号,全局唯一2016062310143088
agrNoString(32)M客户签约的协议号201606238888888
currencyString(3)M币种,目前只支持人民币,固定为 RMBRMB
amountString(20)M订单金额,以分为单位,如2000表示20.00元2000
trnAbsString(50)M交易摘要,简要描述交易的关键信息科兴停车费
noticeUrlString(100)M结果异步通知URL (地址仅支持http 80端口和https 443端口),用于银行异步发送交易结果http://notice.xxabc.com
subMerchantNoString(30)O二级商户编码,必须为数字或英文字母
subMerchantNameString(100)O二级商户名称
subMerchantTPCodeString(7)O二级商户类别编码,必须为数字或英文字母
subMerchantTPNameString(100)O二级商户类别名称

请求示例:

json报文组织:

{
    "version":"1.0",
    "sign":"见签名处理章节",
    "signType":"SHA-256",
    "reqData":{
        "dateTime":"20160623101430",
        "txCode":"CMSK",
        "branchNo":"0755",
        "merchantNo":"002346",
        "merchantSerialNo":"2016062310143088",
        "agrNo":"201606238888888",
        "currency":"RMB",
        "amount":"2000",
        "trnAbs":"科兴停车费",
        "noticeUrl":"http://notice.xxabc.com"
        }
}

表单组织:

<form action="请求地址" method="post" >
      <input type="hidden" name="jsonRequestData" value='以上json字符串' /> 
      <input type="hidden" name="charset"  value='UTF-8' />
</form>

待签名字符串(未包含支付密钥):

agrNo=201606238888888&amount=2000&branchNo=0755¤cy=RMB&dateTime=20160623101430&merchantNo=002346&merchantSerialNo=2016062310143088?iceUrl=http://notice.xxabc.com&trnAbs=科兴停车费&txCode=CMSK

4. 响应报文

参数名类型(长度)必填描述示例
versionString(3)M固定为1.01.0
charsetString(8)M参数编码,固定为UTF-8UTF-8
signStringM报文签名,使用商户支付密钥
对rspData内的数据进行验签

signTypeStringM签名算法,固定为SHA-256SHA-256
rspData应答数据


rspCodeStringM处理结果返回码

SUC0000:扣款请求处理成功

CMBMB05:业务处理超时,请等待回调通知或稍后查询交易结果

其他:请求处理失败
SUC0000
rspMsgStringM处理结果返回码的描述信息请求处理成功
dateTimeString(14)M银行响应该请求的时间,格式yyyyMMddHHmmss20160623101430
merchantSerialNoString(32)M商户交易请求流水号,全局唯一2016062310143088
agrNoString(32)M客户签约的协议号201606238888888
交易结果明确时返回以下信息:
bankSerialNoString(30)M银行处理该请求的流水号(请以异步通知接口或查询接口的返回值为准)2016062310143099
amountString(20)M订单金额,以元为单位,如10.01表示10元零1分10.01
fee_amtString(20)M手续费金额,以元为单位,如0.07表示 零元7分0.07
card_typeString(2)M交易卡类型
02 本行借记卡
02
discountAmountString(20)M优惠金额,以元为单位,如0.07表示 零元7分0.02
discountFlagString(1)M优惠标识(收款通知)Y:有优惠 N:无优惠Y
settleDateString(8)M银行账务日期(YYYYMMDD),用于商户与银行对账20161212

相应示例:

正常json报文组织:

{
    "version":"1.0",
    "charset":"UTF-8",
    "sign":"见签名处理章节",
    "signType":"SHA-256",
    "rspData":{
        "rspCode":" SUC0000 ",
        "rspMsg":"收款成功",
        "dateTime":"20160623101430",
        "merchantSerialNo":"2016062310143088",
        "bankSerialNo":"2016062310143099",
        "agrNo":"1234567891234568789",
        "amount":"10.01",
        "settleDate":"20161212"
        }
}

待验签字符串(未包含支付密钥):

agrNo=1234567891234568789&amount=10.01&bankSerialNo=2016062310143099&dateTime=20160623101430&merchantSerialNo=2016062310143088&rspCode=CMBRECV&rspMsg=收款成功&settleDate=20161212

异常json报文组织:

{
    "version":"1.0",
    "charset":"UTF-8",
    "sign":"见签名处理章节",
    "signType":"SHA-256",
    "rspData":{
        "rspCode":"DCB0003",
        "rspMsg":"DCB0003 请求报文JSON格式错误!",
        "txCode":"",
        "dateTime":"20160817141216"
    }
}

待验签字符串(未包含支付密钥):

dateTime=20160817141537&rspCode=DCB0003&rspMsg=DCB0003 请求报文JSON格式错误!&txCode=

5. 错误码

错误码错误描述解决方案
CMBMB01商户不支持该交易类型商户非免密商户,不能进行免密支付,请联系招行业务人员确认/修改商户参数
CMBMB03系统繁忙,请稍后重试系统处理繁忙,可以稍后重新发起本交易
CMBMB05业务处理超时,请等待回调通知或稍后查询交易结果系统处理繁忙,可以稍后做单笔查询或等待银行回调通知
CMBMB33客户协议不存在没有签约或者该协议已注销,请先调用签约接口进行客户签约
CMBMB38币种不正确币种必须为RMB
CMBMB41交易处理失败因余额不足、卡片异常等,具体原因请参考错误描述信息
CMBMB45协议已注销协议已关闭,请重新签约。
CMBMB62商户交易流水号重复商户交易流程号需要保持全局唯一,请重新生成
CMBMB67该协议为非免密协议请调用开通免密接口开通免密支付功能,或者调用签约接口重新签约。
CMBMB68该协议未绑定银行卡请重新发起签约
CMBMB82交易金额不能小于或等于0请检查交易金额,最低支付0.01元。
CMBMB97请求参数错误根据提示信息中括号里的内容,修改请求参数。
如:请求参数错误(商户交易日期),
检查”商户交易日期”字段的内容是否正确
DCB0001DCB0001 贵方发送错误报文数
太多,已被限制访问!

异常操作错误太多,请根据之前的错误反馈
进行更改,限制将在一定时间后自动解除
DCB0002DCB0002 请求报文数据不能为空!输入参数jsonRequestData拼写正确,并且值非空
DCB0003DCB0003 请求报文JSON格式错误!输入参数jsonRequestData为合法的JSON格式
DCB0004DCB0004 请求报文数据有误;
请求报文长度过长
缩短输入参数jsonRequestData内容
DCB0004DCB0004 请求报文数据有误:……错误消息有以下这些情况,请根据对应提示修改。
接口版本号version值不正确
参数编码charset值不正确
签名sign不能为空
签名算法signType值不正确
请求数据reqData不能为空
时间戳dateTime位数超长或者为0
时间戳dateTime不能为空
交易功能码txCode位数超长或者为0
交易功能码txCode不能为空
商户号merchantNo位数超长或者为0
商户号merchantNo不能为空
分行号branchNo位数超长或者为0
分行号branchNo不能为空
商户流水号merchantSerialNo位数超长或者为0
商户流水号merchantSerialNo不能为空
客户协议号agrNo位数超长或者为0
客户协议号agrNo不能为空
DCB0005DCB0005 商户未开通接入平台功能;
商户号:……
商户号需要开通接入平台功能
DCB0006DCB0006 源IP地址不在商户IP白名单中;
商户号:…;IP地址:…
商户需要提供IP添加到白名单中
DCB0007DCB0007 调用功能不可用;
调用功能代码:……
调用的功能不支持,请输入支持的功能代码
DCB0008DCB0008 签名验证失败:……错误消息有以下情况,请根据对应提示修改。
签名时间戳格式不正确!
签名时间错误,签名已经失效。
验签异常:……
DCB0010DCB0010 获取商户密钥失败;商户号:……商户未正确开通接入平台功能,请按正规流程进行登记开通
DCB0017DCB0017 与业务系统的通讯失败:……错误消息有以下情况,请稍后再试
[MIDServerComNP]业务系统繁忙
[MIDServerComNP]连接业务服务器失败:…
[MIDServerComNP]接收业务系统通讯报文头失败
[MIDServerComNP]接收业务系统通讯报文头非法
[MIDServerComNP]接收业务系统通讯报文包体长度不正确.[…]
[MIDServerComNP]与业务系统通讯异常:…
DCB0018DCB0018 与业务系统的通讯异常:……错误消息有以下情况,请联系招行相关技术支持人员。
解析中间业务平台返回报文失败
DCB0019DCB0019 企业网银签名异常:……请联系招行相关技术支持人员
DCB0020DCB0020 服务器繁忙,请稍后再试。当前服务器负载达到上限,请稍后再试。
DCB0021DCB0021 解析返回报文失败请联系招行相关技术支持人员

6. FAQ

Q1. 收款接口校验的逻辑是什么?
      1)商户每期扣款金额必须小于等于签约接口上送的“周期最大扣款金额”;
      2)商户发起扣款可在周期内的任一时间发起,每个周期内每条协议仅有一次成功扣款机会,上期如未发生扣款,资格不会叠加到下期;
      3)当前周期发生收款成功的交易,然后对该交易发起退款,则该周期内也不允许再次发起扣款;
      4)如果签约时传入“周期总期数”,则收款时会校验协议是否已超期失效:到期后一网通系统将协议自动置为失效,不允许商户再次发起收款。