PC扫码支付

PC端生成扫码支付页面API

请求地址

生产环境
https://netpay.cmbchina.com/netpayment/BaseHttp.dll?PC_EUserPay

测试环境
http://121.15.180.66:801/netpayment/BaseHttp.dll?PC_EUserPay

请求报文

报文的参数名:jsonRequestData,参数值JSON格式见下表

参数名称JSON键值类型(长度)必填描述示例
接口版本号versionString(3)M固定为”1.0”1.0
参数编码charsetString(8)M固定为“UTF-8”UTF-8
报文签名signStringM使用支付密钥对reqData内的数据进行签名
签名算法signTypeStringM固定为“SHA-256”SHA-256
请求数据reqData
请求时间dateTimeString(14)M格式:yyyyMMddHHmmss
商户发起该请求的当前时间,精确到秒
20161209112230
分行号branchNoString(4)M商户分行号,4位数字0755
商户号merchantNoString(6)M商户号,6位数字000054
订单日期dateString(8)M格式:yyyyMMdd20161209
订单号orderNoString(32)M支持6-32位(含6和32)间任意位数的订单号,支持不固定位数,支持数字+字母(大小字母)随意组合。由商户生成,一天内不能重复。订单日期+订单号唯一定位一笔订单。9999000001
订单金额amountString(14)M格式:xxxx.xx
固定两位小数,最大11位整数
0.01
过期时间跨度expireTimeSpanString(2)M必须为大于零的整数,单位为分钟。该参数指定当前支付请求必须在指定时间跨度内完成(从系统收到支付请求开始计时),否则按过期处理。一般适用于航空客票等对交易完成时间敏感的支付请求。1
成功支付结果通知地址payNoticeUrlString(256)M商户接收成功支付结果通知的地址。http://www.merchant.com/path/payNotice.do
成功支付结果通知附加参数payNoticeParaString(256)O该参数在发送成功支付结果通知时,将原样返回商户注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。12345678|ABCDEFG|HIJKLM
商品描述productDescString(40)O1. 显示在PC端扫码支付页面
2. 在支付成功后,附加在短信通知中
3. 最大40个字节,1个中文占用2个字节
4. 支持中文、字母(大小写)、数字、空格、标点符号,任意组合
5. 不支持英文格式的单双引号、加号(+)、反斜杠(\)、&

成功页返回商户地址returnUrlString(256)O支付成功页面上“返回商户”按钮跳转地址。为空则不显示返回商户按钮。原生APP可传入一个特定地址(例如:Http://CMBNPRM),并拦截处理自行决定跳转交互。
支付结果前端通知API中的结果将在本地址的参数中返回。以POST的方式返回本地址。
http://www.merchant.com/path/return.do
客户IPclientIPString(64)O商户取得的客户IP,如果有多个IP用逗号”,”分隔。99.12.38.165
允许支付的卡类型cardTypeString(1)O默认对支付卡种不做限制,储蓄卡和信用卡均可支付
A:储蓄卡支付,即禁止信用卡支付

协议号agrNoString(32)O客户协议号。支持的字符集:数字、字母(大小字母)、 -_ 两个特殊字符,-_ 注意是英文半角的。
未签约(首次支付)客户,填写新协议号,用于协议开通;已签约(再次支付)客户,填写该客户已有的协议号。
商户必须对协议号进行管理,确保客户与协议号一一对应。
协议号允许为空,若协议号字段为空,则不进行签约,直接登录后完成支付;如商户上送协议号签约成功,客户再次支付无需进行登录操作。
12345678901234567890
协议开通请求流水号merchantSerialNoString(20)C协议开通请求流水号,开通协议时必填。2016062014308888
商户用户IDuserIDString(20)O用于标识商户用户的唯一ID。商户系统内用户唯一标识,不超过20位,数字字母都可以,建议纯数字。2016062388888
商户用户手机号mobileString(11)O商户用户的手机号18202532653
风险等级riskLevelString(4)O用户在商户系统内风险等级标识
成功签约结果通知地址signNoticeUrlString(100)C上送协议号且首次签约,必填。商户接收成功签约结果通知的地址。http://www.merchant.com/path/signNotice.do
成功签约结果通知附加参数signNoticeParaString(128)O该参数在发送成功签约结果通知时,将原样返回商户。注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。12345678|ABCDEFG|HIJKLM
加密类型encrypTypeStringORC4:使用RC4算法对加密数据进行加密,加密密钥为支付密钥。
DES:使用DES算法对加密数据进行加密,加密密钥为商户支付密钥的前8位,不足8位则右补0。
注意:如果加密数据字段非空,该字段必填。

加密数据encrypDataStringOjson格式写入的加密数据,并使用encrypType指定的算法加密。
使用信息
使用encrypType指定的加密算法加密后的扩展信息。明文格式字符串格式如:{"addressCity":"440300","addressMobile":"18106989120","productType":"000518"}
注意:加密后的密文必须转换为16进制字符串

开通实名认证时,需上送以下信息(商户默认不上送):
客户实名认证方式userAuthTypeString(2)O主动支付客户实名认证方式:
A:按照免密支付协议号对应的客户信息认证
A
认证信息userAuthInfoString(32)OA模式下上送免密支付协议号111222333


请求示例

1.json报文组织:

{
    "version":"1.0",
    "charset":"UTF-8",
    "sign":"见签名处理章节",
    "signType":"SHA-256",
    "reqData":{
        "dateTime":"20161209112230",
        "branchNo":"0755",
        "merchantNo":"000054",
        "date":"20161209",
        "orderNo":"9999000001",
        "amount":"0.01",
        "expireTimeSpan":"30",
        "payNoticeUrl":"http://www.merchant.com/path/payNotice.do",
        "payNoticePara":"12345678|ABCDEFG|HIJKLM",
        "productDesc":"商品描述",
        "returnUrl":"http://www.merchant.com/path/return.do",
        "clientIP":"99.12.38.165",
        "cardType":"A",
        "agrNo":"12345678901234567890",
        "merchantSerialNo":"2016062014308888",
        "userID":"2016062388888",
        "mobile":"18202532653",
        "riskLevel":"",
        "signNoticeUrl":"http://www.merchant.com/path/signNotice.do",
        "signNoticePara":"12345678|ABCDEFG|HIJKLM",
        " encrypData":
        "FC7788996853803BB6981F406BA84939CE96B8D57FFB20B653078B181FA9691D7CFF00D1D3EF21E6B338A3FD33690CAF12078BE885BB49F6016CF5A0314D21BF49738629F8386CB437A76A8DBE1E7E932DBDB18B7C69A8D10900FB8A3C98CB48833B5800A541DD6B5A12F65508C3BCD1D51B32DD02CCE362BB5CE4D95E5D29921E603BBE3CA5B650652589011304CC2969E2A1046F91A1849B70001FE23EA8592560BE4FB7994D51BC7E7F5F5E08474F7090A44D635F2BFD7353B081DF80613817FD357CD472392A2EFEB1DA52D72DADD3BD5725FE42FA9D4B19",
        "encrypType":"RC4"
        "userAuthType":"A",
        "userAuthInfo":"111222333"
    }
}

2.表单组织:

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

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

agrNo=12345678901234567890&amount=0.01&branchNo=0755&cardType=A&clientIP=99.12.38.165&date=20161209&dateTime=20161209112230&encrypData=FC7788996853803BB6981F406BA84939CE96B8D57FFB20B653078B181FA9691D7CFF00D1D3EF21E6B338A3FD33690CAF12078BE885BB49F6016CF5A0314D21BF49738629F8386CB437A76A8DBE1E7E932DBDB18B7C69A8D10900FB8A3C98CB48833B5800A541DD6B5A12F65508C3BCD1D51B32DD02CCE362BB5CE4D95E5D29921E603BBE3CA5B650652589011304CC2969E2A1046F91A1849B70001FE23EA8592560BE4FB7994D51BC7E7F5F5E08474F7090A44D635F2BFD7353B081DF80613817FD357CD472392A2EFEB1DA52D72DADD3BD5725FE42FA9D4B19&encrypType=RC4&expireTimeSpan=30&merchantNo=000054&merchantSerialNo=20161209112230&mobile=18202532653&orderNo=9999000001&payNoticePara=12345678|ABCDEFG|HIJKLM&payNoticeUrl=http://www.merchant.com/path/WAPProcResult.dll&returnUrl=http://www.merchant.com/path/return.do&riskLevel=&signNoticePara=12345678|ABCDEFG|HIJKLM&signNoticeUrl=http://www.merchant.com/path/signNotice.do&userID=2016062388888

4.扩展信息

扩展信息(encrypData)用于商户上送一些订单信息、用户信息。 json格式写入扩展信息,并使用encrypType指定的算法加密

a)扩展信息字段可以传的参数

参数名称JSON键值类型(长度)必填描述示例
商户用户注册ID注册时间userIDRegisterTimeString(26)O时间戳。
格式YYYY-MM-DD hh:mm:ss
2016-01-01 14:33:22
是否是24H内注册IDnewRegisterFlagString(1)OY/NY
粗略地理位置cityCodeString(6)O使用行政区划代码,六位440300
订单收货城市addressCityString(6)O使用行政区划代码,六位440300
订单收货人手机号addressMobileString(11)O11位手机号或手机号未4位。18025369523
产品及服务标识productTypeString(12)O

1)扩展信息字段的使用说明

json格式写入扩展信息,并使用encrypType指定的算法加密。加密算法如下:

首先将需传入的风控参数拼接成json,再使用RC4或DES加密生成16进制的字符串即为encrypData字段。encrypType取值为RC4时,密钥为商户支付密钥;取值为DES时,密钥为商户支付密钥的前8位,不足8位则右补0。RC4与DES算法参考附录中的RC4代码示例和DES代码示例。

响应报文

网页直接展示结果,无响应报文。
签约成功和支付成功后有异步结果通知,失败无通知。

错误码

错误码描述解决方案
请求参数错误:
NP1016分行号格式错误参数branchNo错误
商户开户分行号,4位数字,请咨询开户的招商银行分支机构;
NP1017商户号格式错误参数merchantNo错误
商户号,6位数字,由银行在商户开户时确定;//收单商户号
NP1020金额格式错误参数amount错误
订单总金额,格式为:xxxx.xx元;
NP1022日期格式错误参数dateTime或date错误
Date: yyyyMMdd,TS:yyyyMMddHHmmss
NP1029订单已过期:请回到商户网站,重新生成订单参数dateTime错误
订单已过期,请求时间和当前系统时间间隔超过30分钟
NP1034商户通知URL地址格式错误参数payNoticeUrl错误
格式要求:“https://”或“http://”开头
NP1035商户通知参数超长参数payNoticePara或signNoticePara错误
参数长度超过128个字节
NP1070商户附加信息中,包含不允许的内容参数payNoticePara或signNoticePara错误
参数值不允许有脚本
NP1071订单过期时间(分钟)格式错误参数expireTimeSpan错误
必须为大于零的整数,单位为分钟。
NP1021订单号格式错误参数orderNo错误
订单号,支持6-32位(含6和32)间任意位数的订单号,支持不固定位数,支持数字+字母(大小字母)随意组合。
NP1107非法一网通支付协议号参数agrNo错误
客户协议号。支持的字符集: 数字、字母(大小字母)、-_ 两个特殊字符,-_ 注意是英文半角的。未签约客户,填写新增的协议号,用于协议开通;签约客户,填写客户协议号。非空。
NP1108非法一网通支付协议开通流水号参数merchantSerialNo错误
字符串,不超过20位。协议开通时非空。
NP1109非法协议商户号参数merchantNo错误
由银行在商户开户时确定。非空。
NP1110非法协议用户ID参数userID错误
字符串,不超过20位。可为空
NP1111非法协议手机号参数Mobile错误
11位数字。可为空
NP1112非法协议开通结果通知命令请求地址参数signNoticeUrl错误
字符串,长度不超过100位。协议开通时非空。
NP1113非法协议开通结果通知命令参数参数signNoticePara错误
字符串,长度不超过128位。可为空
NP1124商户URL返回地址格式错误参数returnUrl错误
格式要求:“https://”或“http://”开头
以下是支付流程中的其他报错:
NP2001该商户只允许使用专业版进行支付只允许进行专业版支付的商户,不允许接入一网通支付
NP2028该商户不允许进行协议支付商户不在一网通支付白名单中
NP4010查询协议支付信息失败查询客户协议信息失败(与中间业务通讯),后面会有具体错误原因: 后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。 错误信息中带错误码“NP8016”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP4011查询一网通用户信息失败查询一网通用户状态失败(与一网通BServer通讯),后面会有具体错误原因: 后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。 错误信息中带错误码“NP8005”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP4012一网通用户状态异常查询一网通用户状态成功,但用户状态异常。根据提示信息进行相应处理。
NP4013查询绑定卡列表信息失败查询绑定卡片列表失败(与一网通BServer通讯,BServer后台对接综合支付平台),后面会有错误原因: 后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。 错误信息中带错误码“NP8005”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP4014抱歉,您解绑了所有卡片,目前绑定卡列表为空,请绑定后重试客户绑定卡片列表中无“支付卡”。
NP0020请求处理失败,请重新提交支付密码解密失败(一般是商户公钥与系统配置的私钥不匹配)
NP4004支付请求处理失败支付请求提交失败(与NPSServer通讯,BServer后台对接收单),后面会有错误原因: 后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。 错误信息中带错误码“NP8005”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP8005BServer业务处理通讯失败与BServer系统通讯失败。需根据场景进行分析:1、如填写完支付密码提交时报错,参看错误码NP4004中“NP8005”处理
NP1122无效订单:签名验证失败Sign加密签名不匹配,检查参数排序是否一致,参数是否按规定来传,算法是否正确
NP1123参数格式不正确检查json格式是否正确
NP1125商户编码错误检查是否使用了规定的编码方式
NP1126商户请求方式错误检查是否使用了规定的请求方式,只支持Post方式
NP1128扩展信息解密错误或扩展信息格式错误EncrypData加密算法有误或参数数据格式错误
NP1129扩展信息加密类型错误EncrypType未送RC4或DES

FAQ

Q1. 招商银行PC页面支付二维码的有效期有多久?
用户进入招行PC支付收银台,二维码有效期开始倒计时,剩余有效时间为“商户发起该请求的时间(datetime)”+ 20分钟 -“招行接收商户请求时的系统时间”。

Q2. 商户如果一直没有接收到回调通知,应该怎么处理?
如果用户一直未扫码,或未确认提交支付请求给招行,即招行支付系统未处理该扣款,则不会主动给商户发送成功回调通知。商户从datetime开始,可通过定时任务调用“单笔订单查询API”确认支付状态,如果超过30分钟后仍未查询到支付成功,则可认为该笔支付交易失败。之后请使用相同的商户订单号重新发起支付。