SDK支付API

请求报文

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

参数名称 JSON键值 类型(长度) 必填 描述 示例
参数编码 charset String(8) M 编码格式,固定为“UTF-8”(默认) UTF-8
接口版本号 version String(3) M 固定为“1.0” 1.0
报文签名 sign String M 使用支付密钥对reqData内的数据进行签名
签名算法 signType String M 固定为“SHA-256” SHA-256
请求数据 reqData 请求数据
请求时间 dateTime String(14) M 格式:yyyyMMddHHmmss
含义:商户发起该请求的当前时间,精确到秒
20161216140241
分行号 branchNo String(4) M 商户分行号,4位数字 0755
商户号 merchantNo String(6) M 商户号,6位数字 000054
订单日期 date String(8) M 格式:yyyyMMdd
含义:订单的日期
20161216
订单号 orderNo String(32) M 订单号,6-32位的数字和字母组合,由商户生成,一天内不能重复。订单日期+订单号唯一定位一笔订单。 9999153784
金额 amount String(14) M 格式:xxxx.xx
固定两位小数,最大11位整数
0.01
过期时间跨度 expireTimeSpan String(2) O 必须为大于零的整数,单位为分钟。
该参数指定当前支付请求必须在指定时间跨度内完成(从系统收到支付请求开始计时),否则按过期处理。一般适用于航空客票等对交易完成时间敏感的支付请求。
30
成功支付结果通知地址 payNoticeUrl String(256) M 商户接收成功支付结果通知的地址,不能带商户参数。若payNoticeUrl参数为空,系统视为不需要通知商户。 http://www.merchant.com/path/payNotice.do
成功支付结果通知附加参数 payNoticePara String(128) O 该参数在发送成功支付结果通知时,将原样返回商户
注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。
aaa
商户用户IP clientIP String(62) O 商户取得的客户IP,如果有多个IP用逗号”,”分隔。 99.12.43.61
允许支付的卡类型 cardType String(1) O 默认对支付卡种不做限制。
如果为A,则只允许储蓄卡支付,禁止信用卡支付;其他值储蓄卡和信用卡均可支付
二级商户编码 subMerchantNo String(30) O 当前订单为商户的二级商户的订单时需要传送;
必须为数字或英文字母
二级商户名称 subMerchantName String(100) O 当前订单为商户的二级商户的订单时需要传送;
二级商户类别编码 subMerchantTPCode String(7) O 当前订单为商户的二级商户的订单时需要传送;必须为数字或字母
二级商户类别名称 subMerchantTPName String(100) O 当前订单为商户的二级商户的订单时需要传送;
允许的支付方式 payModeType String(2) O 默认不设限制,允许微信支付。
空或00:不设限制; 01:仅不允许微信支付;
协议号 agrNo String(32) O 客户协议号。支持数字、字母(大小字母)、“-””_”两个特殊字符(注意-_是英文半角的)。
未签约(首次支付)客户,填写新协议号,用于协议开通;已签约(再次支付)客户,填写该客户已有的协议号。
商户必须对协议号进行管理,确保客户与协议号一一对应。
12345678901234500000
协议开通请求流水号 merchantSerialNo String(30) C 协议开通请求流水号,开通协议时必填。 2016062014308880
商户用户ID userID String(20) O 用于标识商户用户的唯一ID。商户系统内用户唯一标识,不超过20位,数字字母都可以,建议纯数字。 2016062388888
经度 lon String(20) O 经度,商户app获取的手机定位数据,如30.949505 30.949505
纬度 lat String(20) O 纬度,商户app获取的手机定位数据,如50.949506 50.949506
风险等级 riskLevel String(4) O 用户在商户系统内风险等级标识
成功签约结果通知地址 signNoticeUrl String(256) C 首次签约,必填。商户接收成功签约结果通知的地址。 http://www.merchant.com/path/signNotice.do
成功签约结果通知附加参数 signNoticePara String(512) O 该参数在发送成功签约结果通知时,将原样返回商户。注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。 12345678|ABCDEFG|HIJKLM
加密类型 extendInfoEncrypType String M 扩展信息的加密算法,扩展信息加密类型,取值为RC4或DES
加密密钥:
取值为RC4时,密钥为商户支付密钥;
取值为DES时,密钥为商户支付密钥的前8位,不足8位则右补0
注意:如果扩展信息字段非空,该字段必填
RC4
扩展信息 extendInfo String M json格式写入的扩展信息,并使用extendInfoEncrypType指定的算法加密
使用详见扩展信息
注意:1.加密后的密文必须转换为16进制字符串。2.以下10个字段为要加密的数据。
FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9

示例报文

1.jsonRequestData报文组织:

{
    "version":"1.0",
    "sign":"见签名处理章节",
    "signType":"SHA-256",
    "reqData":{
        "dateTime":"20161216140241",
        "branchNo":"0755",
        "merchantNo":"000054",
        "date":"20161216",
        "orderNo":"9999153784",
        "amount":"0.01",
        "expireTimeSpan":"30",
        "payNoticeUrl":"http://www.merchant.com/path/payNotice.do",
        "payNoticePara":"aaa",
        "clientIP":"99.12.43.61",
        "cardType":"",
        "subMerchantNo":"",
        "subMerchantName":"",
        "subMerchantTPCode":"",
        "subMerchantTPName":"",
        "payModeType":"",
        "agrNo":"12345678901234500000",
        "merchantSerialNo":"2016062014308880",
        "userID":"2016062388888",
        "lon":"30.949505",
        "lat":"50.949506",
        "riskLevel":"",
        "signNoticeUrl":"http://www.merchant.com/path/signNotice.do",
        "signNoticePara":"12345678|ABCDEFG|HIJKLM",
        "extendInfo":"FC77A8996853803BB6981F406BA84939CE96B8D57FFB20B653078B181FA9691D7CFF00D1D3EF21E6B338A3FD33490CAF12078BE885BB49F6016CF5A0314D21BF49738609F8386CB437A76A8DBE1E7E932DBDB18B7C69A8F10900FB8A3C98CB48833B5800A541DD6B5A12F65508C39CD1D51B32DD02CCE362BB5CE4D95E5D29921E603BBE3CA5B650652589013304CC2969E2A1046F91A1849B70001FE23EA8792560BE4FB7994D51BC7E7F5F5E08474F7090A44D435F2BFD7353B081DF80613817FD357CD472390A2EFEB1DA52D72DADD3BD5725FE42FA9D4B19",
        "extendInfoEncrypType":"RC4"
    }
}

2.SDK接口的requestData(json字符串先做url编码再进行拼接)示例:

charset=utf-8&jsonRequestData=%7B%22version%22%3A%221.0%22%2C%22sign%22%3A%22E90F8FC43728912AE76510FA0EA867CEC0E8557060FA90C67ABEFDC9DB489CB9%22%2C%22signType%22%3A%22SHA-256%22%2C%22reqData%22%3A%7B%22agrNo%22%3A%22201707231234515%22%2C%22amount%22%3A%220.01%22%2C%22branchNo%22%3A%220755%22%2C%22cardType%22%3A%22%22%2C%22clientIP%22%3A%2299.6.150.83%22%2C%22date%22%3A%2220181107%22%2C%22dateTime%22%3A%2220181107193657%22%2C%22expireTimeSpan%22%3A%2230%22%2C%22extendInfo%22%3A%22FC77A8996853803BB6981F406BA84939CE96B8D57FFB20B653078B181FA9691D7CFF00D1D3EF21E6B338A3FD33490CAF12078BE885BB49F6016CF5A0314D21BF49738609F8386CB437A76A8DBE1E7E932DBDB18B7C69A8F10900FB8A3C98CB48833B5800A541DD6B5A12F65508C39CD1D51B32DD02CCE362BB5CE4D95E5D29921E603BBE3CA5B650652589013304CC2969E2A1046F91A1849B70001FE23EA8792560BE4FB7994D51BC7E7F5F5E08474F7090A44D435F2BFD7353B081DF80613817FD357CD472390A2EFEB1DA52D72DADD3BD5725FE42FA9D4B480F1804D6C9ADB7385C7CD1DCDF9F238A40DFF28BB3BB14%22%2C%22extendInfoEncrypType%22%3A%22RC4%22%2C%22lat%22%3A%2230.949505%22%2C%22lon%22%3A%2250.949506%22%2C%22merchantNo%22%3A%22000054%22%2C%22merchantSerialNo%22%3A%2220181107193657%22%2C%22mobile%22%3A%2213888888888%22%2C%22orderNo%22%3A%229999736092%22%2C%22payNoticePara%22%3A%22aaa%22%2C%22payNoticeUrl%22%3A%22https%3A%2F%2F99.6.150.226%3A44300%22%2C%22riskLevel%22%3A%223%22%2C%22signNoticePara%22%3A%22bb%22%2C%22signNoticeUrl%22%3A%22http%3A%2F%2F99.6.150.51%2F1.html%22%2C%22userID%22%3A%220000000001%22%2C%22subMerchantNo%22%3A%22%22%2C%22subMerchantName%22%3A%22%22%2C%22subMerchantTPCode%22%3A%22%22%2C%22subMerchantTPName%22%3A%22%22%2C%22payModeType%22%3A%22%22%7D%7D 

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

agrNo=201707231234515&amount=0.01&branchNo=0755&cardType=&clientIP=99.6.150.83&date=20180920&dateTime=20180920162357&expireTimeSpan=30&extendInfo=FC77A8996853803BB6981F406BA84939CE96B8D57FFB20B653078B181FA9691D7CFF00D1D3EF21E6B338A3FD33490CAF12078BE885BB49F6016CF5A0314D21BF49738609F8386CB437A76A8DBE1E7E932DBDB18B7C69A8F10900FB8A3C98CB48833B5800A541DD6B5A12F65508C39CD1D51B32DD02CCE362BB5CE4D95E5D29921E603BBE3CA5B650652589013304CC2969E2A1046F91A1849B70001FE23EA8792560BE4FB7994D51BC7E7F5F5E08474F7090A44D435F2BFD7353B081DF80613817FD357CD472390A2EFEB1DA52D72DADD3BD5725FE42FA9D4B19&extendInfoEncrypType=RC4&lat=30.949505&lon=50.949506&merchantNo=000054&merchantSerialNo=20180920162357&orderNo=9999687312&payModeType=&payNoticePara=aaa&payNoticeUrl=https://99.6.150.226:44300&riskLevel=3&signNoticePara=bb&signNoticeUrl=http://99.6.150.51/1.html&subMerchantName=&subMerchantNo=&subMerchantTPCode=&subMerchantTPName=&userID=0000000001 

4.扩展信息

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

字段名称 参数 类型 必填 示例值 描述
订单收货城市 addressCity String(6) O 440300 商户接口上送。使用行政区划代码,六位
订单收货手机号 addressMobile String(11) O 18106989120 商户接口上送。尽量提供完整号码,如商户不愿意提供,可仅提供后四位
商品及服务标识 productType String(12) O 000518 商户接口上送。最大长度
商户用户注册ID注册时间 userIDRegisterTime String O
是否是24H内注册ID newRegisterFlag String O
粗略地理位置 cityCode String O
操作系统类型 deviceOS String O
IMEI deviceIMEI String O
IDFA deviceIDFA String O
商户用户手机号 mobile String(11) M 18202532653 商户用户的手机号

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

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

首先将需传入的风控参数拼接成json,再使用RC4或DES加密生成16进制的字符串即为extendInfo字段。extendInfoEncrypType取值为RC4时,密钥为商户支付密钥;

取值为DES时,密钥为商户支付密钥的前8位,不足8位则右补0。RC4与DES算法参考附录中的RC4代码示例和DES代码示例。

2)加密结果的样例

加密前:

{"UserIDRegisterTime":"2016-01-01 14:33:22","NewRegisterFlag":"N","CityCode":"440300","AddressCity":"440300","AddressMobile":"15867147111","ProductType":"pt","DeviceOS":"ANDROID","DeviceIMEI":"IME","DeviceIDFA":"IDFA","mobile":"13888888888"}

RC4加密后:

FC77A8996853803BB6981F406BA84939CE96B8D57FFB20B653078B181FA9691D7CFF00D1D3EF21E6B338A3FD33490CAF12078BE885BB49F6016CF5A0314D21BF49738609F8386CB437A76A8DBE1E7E932DBDB18B7C69A8F10900FB8A3C98CB48833B5800A541DD6B5A12F65508C39CD1D51B32DD02CCE362BB5CE4D95E5D29921E603BBE3CA5B650652589013304CC2969E2A1046F91A1849B70001FE23EA8792560BE4FB7994D51BC7E7F5F5E08474F7090A44D435F2BFD7353B081DF80613817FD357CD472390A2EFEB1DA52D72DADD3BD5725FE42FA9D4B480F1804D6C9ADB7385C7CD1DCDF9F238A40DFF28BB3BB14

DES加密后:

b03a08bbd94a3b21554325f8db18256f38a3cb7d158853c1318af38fbebe208f1795279acc58deed1003ee744dceb7d5554325f8db18256f40ab6a3753b8fc7a8a1b1a83f83dcf43327d026813dcbdca6a4c5448bc838f0d473757290e357c2702e3e12fe81f3ab8cac5790dd4434673e80b93e2924754225a08679ddbd5d22b67b0f76837f26f069242cd4c263fde614f732af955925b834333974835892a1b051eca9f5aef7cd4eb7abd6b6327d0aa03df934ced517aae870a4bccb99e8fc54a940557ed0e1d4670eee0c6da97829223d6aa182241e0500c2f7cafab0ab326

响应报文

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

错误码

错误码 描述 解决方案
请求参数错误:
NP1016 分行号格式错误 参数branchID错误
商户开户分行号,4位数字,请咨询开户的招商银行分支机构;
NP1017 商户号格式错误 参数merchantNo错误
商户号,6位数字,由银行在商户开户时确定;//收单商户号
NP1020 金额格式错误 参数amount错误
订单总金额,格式为:xxxx.xx元;
NP1021 订单号格式错误 参数orderNo错误
订单号,必须为6位或10位长数字
NP1022 日期格式错误 参数date错误
Date:yyyyMMdd
NP1034 商户通知URL地址格式错误 参数payNoticeUrl错误
格式要求:“https://”或“http://”开头
NP1035 商户通知参数超长 参数paynoticPara错误
参数长度超过128个字节
NP1070 商户附加信息中,包含不允许的内容 参数paynoticPara错误
参数值不允许有脚本
NP1071 订单过期时间(分钟)格式错误 参数expireTimeSpan错误
必须为大于零的整数,单位为分钟。
NP1097 二级商户号格式不正确 二级商户号格式是否是全数字或者字母组合
NP1098 二级商户号长度超长 二级商户号最大长度为30
NP1099 二级商户类型编码格式不正确 二级商户类型编码为全数字
NP1100 二级商户类型编码长度超长 二级商户类型编码最大长度
NP1105 非法二级商户名称 二级商户名称最大长度为100
NP1106 非法二级商户类别名称 二级商户别名称最大长度为100
NP1122 商户签名不匹配 订单内容被篡改过,无效订单不予处理
NP1123 无效的Json参数 商户输入JSON参数不正确
NP1124 无效的商户返回URL Url格式不正确
NP1126 Http请求方式不正确 只支持Post请求方式
NP1129 无效的加密类型 加密类型只支持RC4或者DES
NP1133 无效的版本号 版本号固定为1.0
NP1134 无效的签名算法 仅支持SHA-256
NP1135 积分类型格式错误 积分仅支持数字,且长度不超过11位
NP1137 商品详情格式错误 长度不超过500
以下是支付流程中的其他报错:
NP2001 该商户只允许使用专业版进行支付 只允许进行专业版支付的商户,不允许接入一网通支付
NP2028 该商户不允许进行协议支付 商户不在一网通支付白名单中
NP4010 查询协议支付信息失败 查询客户协议信息失败(与中间业务通讯),后面会有具体错误原因:
后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。
错误信息中带错误码“NP8016”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP4011 查询一网通用户信息失败 查询一网通用户状态失败(与一网通BServer通讯),后面会有具体错误原因:
后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。
错误信息中带错误码“NP8005”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP4012 一网通用户状态异常 查询一网通用户状态成功,但用户状态异常。根据提示信息进行相应处理。
NP4013 查询绑定卡列表信息失败 查询绑定卡片列表失败(与一网通BServer通讯,BServer后台对接综合支付平台),后面会有错误原因:
后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。
错误信息中带错误码“NP8005”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP4014 抱歉,您解绑了所有卡片,目前绑定卡列表为空,请绑定后重试 客户绑定卡片列表中无“支付卡”。
NP0020 请求处理失败,请重新提交 支付密码解密失败(一般是商户公钥与系统配置的私钥不匹配)
NP4004 支付请求处理失败 支付请求提交失败(与NPSServer通讯,BServer后台对接收单),后面会有错误原因:
后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。
错误信息中带错误码“NP8005”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP8005 BServer业务处理通讯失败 与BServer系统通讯失败。需根据场景进行分析:1、如填写完支付密码提交时报错,参看错误码NP4004中“NP8005”处理
NP1122 无效订单:签名验证失败 Sign加密签名不匹配,检查参数排序是否一致,参数是否按规定来传,算法是否正确
NP1123 参数格式不正确 检查json格式是否正确
NP1125 商户编码错误 检查是否使用了规定的编码方式
NP1126 商户请求方式错误 检查是否使用了规定的请求方式,只支持Post方式

关于网站迁移公告


为提供更优质的开发技术支持,本网站已于2019年8月12日正式迁移至新域名http://openhome.cmbchina.com/paynew/pay/Home,敬请访问并收藏。原网站域名已停止更新维护,请以新网站提供的文档信息为准。

由此给您带来的不便,敬请谅解。


招商银行一网通支付技术支持小组

2019年8月12日