商户http

京东支付手机网页即时到账接口版本(V1.
0.
0)网银在线(北京)科技有限公司目录1文档说明31.
1功能描述31.
2阅读对象31.
3术语32京东支付流程43接口43.
1支付请求接口参数43.
1.
1接口介绍43.
1.
2参数列表53.
1.
3参数特殊说明53.
1.
4敏感信息加密63.
1.
5样例63.
2异步通知参数73.
2.
1说明73.
2.
2通知报文列表73.
2.
3通知报文特殊说明83.
2.
4样例83.
3退款申请接口93.
3.
1说明93.
3.
2退款申请接口参数列表103.
3.
3退款申请返回参数列表113.
4交易查询接口123.
4.
1说明123.
4.
2查询接口请求参数列表123.
4.
3查询接口返回参数列表134附录144.
1交易返回状态编码表144.
2交易返回信息编码表144.
3交易类型编码表164.
4京东支付退款/查询RSA公钥161文档说明功能描述京东支付手机网页即时到帐接口为第三方手机网页应用提供发起支付请求,并引导用户完成支付过程.
支付完成以后,通过同步、异步两种方式通知第三方网页应用服务器.
它的优势是支付金额即时从消费者的银行账户扣除,用户支付过程简便、安全,界面新颖,再次支付更加便捷.
同时,京东支付又提供了自动退款,以及交易结果查询接口.
交易结果查询接口是为了防止商户长时间没有接收到同步、异步结果通知的情况而设计,在这种情况下,商户可以通过交易查询接口进行单笔或者批量查询交易结果,进而更新用户订单状态.

阅读对象本文档面向商户系统设计人员、编程人员及测试人员.
该人员需要具备一定的网站开发能力,了解ASP、PHP、JAVA、ASP.
NET等开发语言中的一种及SQL数据库语言.
术语名词解释商户指已注册成为网银在线支付产品的用户、并使用网银在线产品实现其收付费功能需求、为其用户提供各类产品或者相关服务的企业或个人.
消费者(用户)指在商户网站等系统购物的企业或个人.
请求通过HTTP/HTTPS协议把数据发送给接收方的过程.
通知京东支付服务器异步通知.
京东支付服务器根据接收到的数据处理完成后,会主动发起通知给商户的服务器,同时携带处理结果信息.
返回页面跳转同步通知.
京东支付服务器根据接收到的数据处理完成后,当前页面从京东支付的页面自动跳转回商户页面,同时携带处理结果信息.
支付失败手机号被冻结、商户违约被冻结支付功能、余额不足、超额、订单已支付、订单金额和支付金额不一致等都会导致支付失败.
京东支付流程用户首先在商户系统的页面上选择商品并下单,点击支付按钮以后,商户系统向京东支付服务支付接口发起支付请求.
商户要根据京东支付接口要求,通过程序得到签名结果以及要传给京东支付服务的订单信息以及商户信息数据集合.
在支付请求的时候把数据集合发送到京东支付服务器.
京东支付服务会首先验证商户的合法性,以及验证订单金额是否被篡改,如果商户非法,或者订单信息被篡改,京东支付服务会直接拒绝此支付请求;反之,则重定向到支付页面,引导用户填入支付的身份信息和银行卡信息,在用户确认之后,从用户的银行卡扣除相应的金额.

如果支付完成以后,京东支付服务会跳转到商户支付请求的时候传入的url,并携带支付结果.
并且,如果支付成功,京东支付服务后台会发送异步通知到商户传入的通知地址,把支付结果通知商户.
接口支付请求接口参数接口介绍支付请求接口提供给商户向京东支付服务发送支付请求数据集合,京东支付服务会根据请求数据验证商户身份,以及验证支付信息是否被篡改.
验证通过后,京东支付服务会把当前页面重定向到支付页面.
如果验证未通过,京东支付服务会把当前页面重定向到商户系统传入的支付失败页面.

调用地址:https://m.
jdpay.
com/wepay/web/pay编码格式:UTF-8调用方式:post数据格式:Form表单参数列表序号参数名称参数编码必填参数类型描述1版本号version是String2.
0(注:1.
0版本不再支持)2用户交易令牌token否String识别用户信息,支付成功后会调用successCallbackUrl返回给商户.
(注:商户可以记录这个token值,当用户再次支付的时候传入该token,用户无需再次输入银行卡信息,直接输入短息验证码进行支付.
)3交易信息签名merchantSign是String用户交易信息签名后的值4商户号merchantNum是String(50)商户在网银登记的商户号5商户备注merchantRemark否String(64)商户备注信息6交易流水号tradeNum是String(30)商户提供的唯一交易流水号(字母和数字)7交易名称tradeName是String(256)商户提供的订单的标题/商品名称/关键字等8交易描述tradeDescription否String(100)商户提供的订单的具体描述信息9交易时间tradeTime是Date商户提供的订单的时间,格式为"年-月-日时:分:秒"例:2014-06-1110:11:1110交易金额tradeAmount是int商户提供的订单的资金总额,单位:分,大于0.
11货币种类currency是String货币类型,固定填CNY12支付成功页面跳转路径successCallbackUrl是String(300)支付成功后跳转的URL,13支付失败页面跳转路径failCallbackUrl是String(300)支付失败时跳转到商户的URL14异步通知地址notifyUrl是String(100)支付完成后,异步通知商户服务相关支付结果参数特殊说明在以上的请求参数中,商户号是在网银在线注册开通京东支付功能的时候,网银在线商户管理系统为用户分配的.
用户的交易令牌在用户第一次支付的时候是没有的.
支付成功以后,该用户的交易令牌会同步返回给商户系统,商户系统可以为该用户存储此交易令牌,并在下一次支付请求时候将令牌传给京东支付服务.
如果支付请求时携带用户交易令牌,那么在支付过程中就不需要用户再填写手机号码、身份信息和银行卡信息.

交易流水号是用来标识每次支付请求的号码,需要商户保证在每一次支付请求的时候交易流水号唯一,多次请求不能使用同一交易流水号,否则京东支付服务在处理后面的支付请求时,会把此交易当做重复支付处理.

交易信息签名使用的签名类型为RSA([java]RSA补位方式为RSA/ECB/PKCS1Padding).
签名的内容为除merchantSign和version,token外所有参数按字母由a-z的顺序排序后以'&'符号连接生成源串,其中非必填字段如无值则使用空串,最后一位'&'要去掉(例如a=1&b=&c=3).
首先把源串使用sha-256加密sha-256加密后转成16进制的字符串作为签名摘要(16进制字母小写,16进制不足2位时在前补"0"),使用RSA对签名摘要进行加密生成签名(RSA加密后为byte数组,使用[标准]BASE64转换为字符串).
注:RSA签名以及验签的时候使用的密钥是商户通过OPENSSL生成的,商户生成RSA密钥对之后需要把公钥配置到网银商户管理后台,使用商户的私钥进行签名,京东支付服务会使用商户公钥对签名进行校验.

支付成功跳转路径,当商户的一次支付请求成功完成支付时,京东支付可将请求重定向到此路径(此操作是用户的可选操作),并在路径后添加"token=xxxx&tradeNum=xxxx"参数,以便商户进行订单信息的付款状态展示(注:商户的真正的订单状态不能依据此请求,此路径只用作展示)支付失败跳转路径,当商户的支付请求支付失败时,京东支付可将请求重定向到此路径(此操作是用户的可选操作),并在路径后添加"tradeNum=xxxx",商户可用于订单信息的状态展示(注:商户的真正的订单状态不能依据此请求)异步通知地址,支付完成后,异步通知商户服务相关支付结果,(真正的支付结果以此通知为准)敏感信息加密支付请求参数中的敏感信息包括序号5至14的参数,在最终提交form表单时,需要进行加密处理(交易签名在此步骤之前),参数中值为空的不进行加密,所有参数以字符串类型进行加密敏感信息加密流程:将网银分配给商户的deskey进行BASE64解码,解码后为byte数组,取前8字节为key以8字节的key为秘钥对参数进行des加密将des加密结果进行BASE64编码为最终结果样例签名源串样例(其中tradeDescription参数为非必填.
)currency=CNY&failCallbackUrl=http://www.
baidu.
com&merchantNum=22312781&merchantRemark=商户备注¬ifyUrl=http://www.
baidu.
com&successCallbackUrl=http://www.
baidu.
com&tradeAmount=10&tradeDescription=&tradeName=交易名称&tradeNum=20001&tradeTime=2014-08-1615:53:08支付请求数据集合参数样例异步通知参数说明异步通知是在支付成功/失败,退款成功/失败的情况下,由网银在线的异步通知服务器自动发送给商户服务器.
通知地址就是商户支付请求的时候传入的'notifyUrl'参数,对于异步通知,网银异步通知系统根据商户通知地址的http访问状态码和返回内容来判断通知是否成功,当收到处理成功标示后,系统不再发送异步通知.
否者,会重复发送异步通知,最多发送5次,时间点分别为支付完成后、支付完成后1分钟、支付完成后3分钟、支付完成后10分钟、支付完成后120分钟.

支付成功标示为返回码"200"并且返回内容"success",其他返回内容均认为商户系统处理异步通知失败.
通知报文列表报文参数数据格式二级参数三级参数参数名称参数说明VERSION明文版本号1.
0.
0MERCHANT明文商户号由网银在线提供TERMINAL明文终端号由网银在线提供DATA按二级参数和三级参数组成XML格式数据,然后使用3DES加密.
TRADETYPE交易类型Q(返回原交易类型)见附录4.
3ID交易号数字或字母AMOUNT交易金额单位:分CURRENCY交易币种人民币:CNYDATE交易日期yyyyMMddTIME交易时间HHmmssNOTE交易备注返回原交易备注,如果没有备注就没有这个参数STATUS交易返回状态成功:0处理中:6失败:7RETRUNCODE交易返回码见附录4.
2DESC交易返回码信息见附录4.
2SIGN明文数据签名MD5签名,签名数据为所有报文参数加签名密钥.
通知报文特殊说明网银在线异步通知报文均经过base64编码,商户服务器收到报文之后需要先做base64反转,之后得到报文内容.
通知报文为xml格式,明文和签名一同发给商户服务器.
DATA域是用商户在网银注册时候给商户生成的DES密钥(实际密钥为密钥字符串经BASE64解码取前8个字节)加密后经过BASE64编码的字符串数据.
签名的源串是将参数VERSION,MERCHANT,TERMINAL,DATA的值按照报文格式顺序,拼接成字符串,加上商户的MD5密钥,中间没有任何连接符.
签名类型是MD5签名(结果为16进制小写字符串).
样例收到的响应参数为resp=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxDSElOQUJBTks+DQogICAgPFZFUlNJT04+MS4wLjA8L1ZFUlNJT04+DQogICAgPE1FUkNIQU5UPjIyMzEwMzE4PC9NRVJDSEFOVD4NCiAgICA8VEVSTUlOQUw+MDAwMDAwMDE8L1RFUk1JTkFMPg0KICAgIDxEQVRBPk42NG1ZWUtKbG93eFhjRHFkSnNMcUZ6MUVQMWZ4bGQwamdHVm1La2FiT0ZXeE9sTU5VWHdBcGNKa24zajZOWE05eVRyOGdIbW9jdjQKTysxTzErVXMxVk1wVzRaUWFiZjdleDNQZWEzMko5VW5vK21LRTlGYnkzMXBhVXFTWlFXRFFqMGlhK3hGVWMvVU16N2EwdWZHZmliNQplQWhpTUZMa0pMaWJGeS9zSmw4QXBWdVRUY3FnOFBjQXdqRHF2R0F2OTd3MHhyYmVLeDl5YmdpSk5xelF0ZjFGZVhFTlllVTZZU2lVClpPQjhyVS9xUW9nSnJ2L2crQUJzY1Iwa0tkM24rRHZ0VHRmbExOWHdJTDh3aHNyaUxBV3BrKzRCdW82aHZsV3U3OXpwWUJXQXJJVS8KdTQycDJFbUYwZHZKRmpTU1BPdjN1Q2paOGlSSzdyV3U0SXlBWGs2cmd2LzdoS1hEbzBLeCtRMUFnbjdiUFIzQVNRcUp2U1lvdit5bAplMkpYZHBmeTNyVU9VZjQ9PC9EQVRBPg0KICAgIDxTSUdOPjE5ZjljZTMyYmU0MTRlZjgyYjg0YTkwNzk0OTNiNzFhPC9TSUdOPg0KPC9DSElOQUJBTks+将得到的resp参数依据字符集经过BASE64解码得到1.
0.
02231031800000001N64mYYKJlowxXcDqdJsLqFz1EP1fxld0jgGVmKkabOFWxOlMNUXwApcJkn3j6NXM9yTr8gHmocv4O+1O1+Us1VMpW4ZQabf7ex3Pea32J9Uno+mKE9Fby31paUqSZQWDQj0ia+xFUc/UMz7a0ufGfib5eAhiMFLkJLibFy/sJl8ApVuTTcqg8PcAwjDqvGAv97w0xrbeKx9ybgiJNqzQtf1FeXENYeU6YSiUZOB8rU/qQogJrv/g+ABscR0kKd3n+DvtTtflLNXwIL8whsriLAWpk+4Buo6hvlWu79zpYBWArIU/u42p2EmF0dvJFjSSPOv3uCjZ8iRK7rWu4IyAXk6rgv/7hKXDo0Kx+Q1Agn7bPR3ASQqJvSYov+yle2JXdpfy3rUOUf4=19f9ce32be414ef82b84a9079493b71a其中签名的源串为VERSION+MERCHANT+TERMINAL+DATA+密钥,并且不带任何连接符,即"1.
0.
02231031800000001N64mYYKJlowxXcDqdJsLqFz1EP1fxld0jgGVmKkabOFWxOlMNUXwApcJkn3j6NXM9yTr8gHmocv4O+1O1+Us1VMpW4ZQabf7ex3Pea32J9Uno+mKE9Fby31paUqSZQWDQj0ia+xFUc/UMz7a0ufGfib5eAhiMFLkJLibFy/sJl8ApVuTTcqg8PcAwjDqvGAv97w0xrbeKx9ybgiJNqzQtf1FeXENYeU6YSiUZOB8rU/qQogJrv/g+ABscR0kKd3n+DvtTtflLNXwIL8whsriLAWpk+4Buo6hvlWu79zpYBWArIU/u42p2EmF0dvJFjSSPOv3uCjZ8iRK7rWu4IyAXk6rgv/7hKXDo0Kx+Q1Agn7bPR3ASQqJvSYov+yle2JXdpfy3rUOUf4=".
值的明文需要通过DES密钥(实际密钥为密钥字符串经BASE64解码取前8个字节)解密后得到.

样例中使用的DES密钥为:xBxXFRV2KrzsokwmyyZJ5qQCxJcEW7y8退款申请接口说明退款申请接口提供给商户发起自动退款的能力.
如果用户在商户系统下单支付以后发起退款,商户验证通过之后可以自动发起退款请求.
同时网银在线商户管理后台提供手动退款的功能.
调用地址:https://m.
jdpay.
com/wepay/refund编码格式:UTF-8调用方式:post数据格式:json退款申请接口参数列表序号参数名称参数编码必填参数类型描述1版本号version是String1.
0(固定值)2商户号merchantNum是String3申请数据data是String退款申请需要的信息3DES4用户退款流水信息签名merchantSign是StringRSA[SHA256[data]]Example{"version":"1.
0","merchantNum":"22294531","merchantSign":"g8HFddOKsvzRgrpNWmo31bLxkiuh6NWch22Hc5sDKJ7LebrXcbxVZhacTcG7423j8L96iCTbNGFQpYQ51lc250lQj+KLsBOidMRyiNvaMfDErv08zGc/lT6FsTXh3EG97nhbOtAw8kwPzTleku4aoy1k3EKuJlhDPCvq3QZ/8XQ=","data":"678c41554777b50774d30e2da6cbd765946fbe95c1214ce3b6238bf4ba034c8391027712af62c26177fc7fa0945211c82155c69827c2213661ca56918027c4ba3fc25905f0478dcf10c2a0a3596f236b89dbd6b285b2d18ec796901f05adaa4be1ce16ff74409d0fe27923eb53fe91d83b4785e0f312553c6f74f80f75f2e70960d837f584d13eae4b4c5b793c80b9ade53adc5281edc1a46eb761a7ce35a7a097e5ea67a6d1ea8aab8655604daa8b53f9f355767c596af72d4701b95b31a679e0f5339997b01c6df304b6eaf9b61d7cb2d3071c462a73964942253d89c026d49335cc2fc785c26b"}data域的参数包括:序号参数名称参数编码必填参数类型描述1交易流水号tradeNum是String不支持批量,数字或字母,标识本次请求2原交易流水号oTradeNum是String数字或字母,标识需要退款的那笔交易流水.
3交易金额tradeAmount是String单位:分4交易币种tradeCurrency是StringCNY5交易日期tradeDate否String(8)yyyyMMdd6交易时间tradeTime否String(6)HHmmss7交易通知地址tradeNotice否String如果为空,交易结束后不主动向商户发送结果通知8交易备注tradeNote否StringExample{"tradeNum":"12345","oTradeNum":"1234","tradeAmount":"1","tradeCurrency":"CNY","tradeDate":"","tradeTime":"","tradeNotice":"","tradeNote":""}申请数据(data)需要做3DES加密,(data首先转换为byte数组,byte数组分为两段数据,前4字节为有效信息长度,后面为有效数据本身,如4字节长度信息加byte数组长度不满8的整数倍,使用0x00补齐加密前数据.
3DES加密前输入数据的前明文格式如下:如:"0X0000000301020300".
0X00000003为有效数据长度,0X010203为3个字节的有效信息,后面加1个字节的0X00补位,使总数据段为8字节的整数倍;Data数据byte长度占4字节Data数据byte内容补齐位(如4字节长度与data长度总和不是8的整数倍,将进行补位)0X000000030X0102030X003DES密钥是商户在注册京东支付服务的时候网银在线商户管理后台为用户生成的.
实际密钥为密钥字符串经BASE64解码取前24个字节申请数据加密流程:1拼接有效信息长度与信息本身.
2使用0x00补齐拼接信息,使拼接信息为8字节的整数倍.
3.
使用实际秘钥对当前拼接信息进行3DES加密.
4.
将加密后的数据转化为16进制格式(0-9,a-f小写字母)字符串)作为最终申请数据(data).
用户退款流水信息签名流程:对最终申请数据(data)进行SHA-256加密转成16进制的字符串(16进制字母小写)进行RSA加密([java]RSA补位方式为RSA/ECB/PKCS1Padding).
RSA加密用到的私钥是需要商户使用OPENSSL生成的,公钥需要配置到京东支付服务端,以便京东支付服务验签.
进行BASE64编码生成签名字符串(merchantSign)退款申请返回参数列表序号参数名称参数编码必填类型描述1返回码resultCode是String2返回描述信息resultMsg是String3返回数据resultData是Object其中resultData数据字段是:序号参数名称参数编码必填类型描述1返回数据信息data是String2返回数据签名sign是String其中,返回数据信息(data)已经做了3DES加密(参阅3.
3.
2退申请数据加密流程).
返回数据签名(参阅3.
3.
2用户退款流水信息签名流程)注:返回数据签名中RSA加密用到的私钥是在商户注册京东支付服务的时候网银在线生成的,公钥会交换给商户,以便商户服务器对返回信息验签.
其中,data域的参数包括:序号参数名称参数编码类型描述1交易号tradeNumString标识本次请求2原交易流水号oTradeNumString标识需要退款的那笔交易流水.
3交易金额tradeAmountString单位:分4交易币种tradeCurrencyString5交易日期tradeDateString(8)yyyyMMdd6交易时间tradeTimeString(6)HHmmss7交易备注tradeNoteString8交易状态tradeStatusString(1)成功:0处理中:6失败:7交易查询接口说明交易查询接口是为了处理商户服务器长时间没有接收到支付结果的情况设计的.
一般情况,支付结果会通过前端同步返回和网银在线服务器的异步通知发动到商户服务.
但是为避免特殊情况商户服务器仍然没有接收到支付结果,这时候商户服务可以通过主动查询交易结果的接口查询支付状态.
查询交易结果接口支持批量查询功能.