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) | M | 必须为大于零的整数,单位为分钟。 该参数指定当前支付请求必须在指定时间跨度内完成(从系统收到支付请求开始计时),否则按过期处理。一般适用于航空客票等对交易完成时间敏感的支付请求。 | 1 | ||
成功支付结果通知地址 | 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(40) | 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(100) | C | 首次签约,必填。商户接收成功签约结果通知的地址。 | http://www.merchant.com/path/signNotice.do | ||
成功签约结果通知附加参数 | signNoticePara | String(512) | O | 该参数在发送成功签约结果通知时,将原样返回商户。注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。 | 12345678|ABCDEFG|HIJKLM | ||
加密类型 | extendInfoEncrypType | String | O | 扩展信息的加密算法,扩展信息加密类型,取值为RC4或DES 加密密钥: 取值为RC4时,密钥为商户支付密钥; 取值为DES时,密钥为商户支付密钥的前8位,不足8位则右补0 注意:如果扩展信息字段非空,该字段必填 | RC4 | ||
扩展信息 | extendInfo | String | O | json格式写入的扩展信息,并使用extendInfoEncrypType指定的算法加密 使用详见扩展信息 注意:1.加密后的密文必须转换为16进制字符串。2.以下10个字段为要加密的数据。 | FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9 | ||
开通实名认证时,需上送以下信息(商户默认不上送): | |||||||
客户实名认证方式 | userAuthType | String(2) | O | 主动支付客户实名认证方式: A:按照免密支付协议号对应的客户信息认证 B:用户信息expendUserID C:用户信息uniqueUserID | A | ||
认证信息 | userAuthInfo | String(32) | O | A模式下上送免密支付协议号 B和C模式用于判断下单用户和支付用户是否一致(B和C模式可能带有+,需做urlencode处理) | 111222333 |
示例报文
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" "userAuthType":"A", "userAuthInfo":"111222333" } }
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) | O | 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 | 分行号格式错误 | 参数branchNo错误 商户开户分行号,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方式 |