APP支付

SDK支付API

请求报文

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

参数名称JSON键值类型(长度)必填描述示例
参数编码charsetString(8)M编码格式,固定为“UTF-8”(默认)UTF-8
接口版本号versionString(3)M固定为“1.0”1.0
报文签名signStringM使用支付密钥对reqData内的数据进行签名
签名算法signTypeStringM固定为“SHA-256”SHA-256
请求数据reqData请求数据

请求时间dateTimeString(14)M格式:yyyyMMddHHmmss
含义:商户发起该请求的当前时间,精确到秒
20161216140241

分行号branchNoString(4)M商户分行号,4位数字0755

商户号merchantNoString(6)M商户号,6位数字000054

订单日期dateString(8)M格式:yyyyMMdd
含义:订单的日期
20161216

订单号orderNoString(32)M订单号,6-32位的数字和字母组合,由商户生成,一天内不能重复。订单日期+订单号唯一定位一笔订单。9999153784

订单金额amountString(14)M格式:xxxx.xx
固定两位小数,最大11位整数
0.01

过期时间跨度expireTimeSpanString(2)M必须为大于零的整数,单位为分钟。
该参数指定当前支付请求必须在指定时间跨度内完成(从系统收到支付请求开始计时),否则按过期处理。一般适用于航空客票等对交易完成时间敏感的支付请求。
1

成功支付结果通知地址payNoticeUrlString(256)M商户接收成功支付结果通知的地址,不能带商户参数。若payNoticeUrl参数为空,系统视为不需要通知商户。http://www.merchant.com/path/payNotice.do

成功支付结果通知附加参数payNoticeParaString(128)O该参数在发送成功支付结果通知时,将原样返回商户
注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。
aaa

商户用户IPclientIPString(62)O商户取得的客户IP,如果有多个IP用逗号”,”分隔。99.12.43.61

允许支付的卡类型cardTypeString(1)O默认对支付卡种不做限制。
如果为A,则只允许储蓄卡支付,禁止信用卡支付;其他值储蓄卡和信用卡均可支付


二级商户编码subMerchantNoString(30)O当前订单为商户的二级商户的订单时需要传送;
必须为数字或英文字母


二级商户名称subMerchantNameString(40)O当前订单为商户的二级商户的订单时需要传送;

允许的支付方式payModeTypeString(2)O默认不设限制,允许微信支付。
空或00:不设限制; 01:仅不允许微信支付;


协议号agrNoString(32)O客户协议号。支持数字、字母(大小字母)、“-””_”两个特殊字符(注意-_是英文半角的)。
未签约(首次支付)客户,填写新协议号,用于协议开通;已签约(再次支付)客户,填写该客户已有的协议号。
商户必须对协议号进行管理,确保客户与协议号一一对应。
12345678901234500000

协议开通请求流水号merchantSerialNoString(30)C协议开通请求流水号,开通协议时必填。2016062014308880

商户用户IDuserIDString(20)O用于标识商户用户的唯一ID。商户系统内用户唯一标识,不超过20位,数字字母都可以,建议纯数字。2016062388888

经度lonString(20)O经度,商户app获取的手机定位数据,如30.94950530.949505

纬度latString(20)O纬度,商户app获取的手机定位数据,如50.94950650.949506

风险等级riskLevelString(4)O用户在商户系统内风险等级标识

成功签约结果通知地址signNoticeUrlString(100)C首次签约,必填。商户接收成功签约结果通知的地址。http://www.merchant.com/path/signNotice.do

成功签约结果通知附加参数signNoticeParaString(512)O该参数在发送成功签约结果通知时,将原样返回商户。注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。12345678|ABCDEFG|HIJKLM

加密类型extendInfoEncrypTypeStringO扩展信息的加密算法,扩展信息加密类型,取值为RC4或DES
加密密钥:
取值为RC4时,密钥为商户支付密钥;
取值为DES时,密钥为商户支付密钥的前8位,不足8位则右补0
注意:如果扩展信息字段非空,该字段必填
RC4

扩展信息extendInfoStringOjson格式写入的扩展信息,并使用extendInfoEncrypType指定的算法加密
使用详见扩展信息
注意:1.加密后的密文必须转换为16进制字符串。2.以下10个字段为要加密的数据。
FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9

开通实名认证时,需上送以下信息(商户默认不上送):

客户实名认证方式userAuthTypeString(2)O主动支付客户实名认证方式:

A:按照免密支付协议号对应的客户信息认证

B:用户信息expendUserID

C:用户信息uniqueUserID

A

认证信息userAuthInfoString(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指定的算法加密

字段名称参数类型必填示例值描述
订单收货城市addressCityString(6)O440300商户接口上送。使用行政区划代码,六位
订单收货手机号addressMobileString(11)O18106989120商户接口上送。尽量提供完整号码,如商户不愿意提供,可仅提供后四位
商品及服务标识productTypeString(12)O000518商户接口上送。最大长度
商户用户注册ID注册时间userIDRegisterTimeStringO

是否是24H内注册IDnewRegisterFlagStringO

粗略地理位置cityCodeStringO

操作系统类型deviceOSStringO

IMEIdeviceIMEIStringO

IDFAdeviceIDFAStringO

商户用户手机号mobileString(11)O18202532653商户用户的手机号

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无效的商户返回URLUrl格式不正确
NP1126Http请求方式不正确只支持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”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP8005BServer业务处理通讯失败与BServer系统通讯失败。需根据场景进行分析:1、如填写完支付密码提交时报错,参看错误码NP4004中“NP8005”处理
NP1122无效订单:签名验证失败Sign加密签名不匹配,检查参数排序是否一致,参数是否按规定来传,算法是否正确
NP1123参数格式不正确检查json格式是否正确
NP1125商户编码错误检查是否使用了规定的编码方式
NP1126商户请求方式错误检查是否使用了规定的请求方式,只支持Post方式