小通分期商户接入手册_1.4

1、小通分期商户接入手册通联商务2016年8月版本号日期维护人说明V1.02016/8/24张调初稿V1.12016/9/5张调添加关键数据域加密V1.22016/11/02张调产品修改，增加附属信息字段V1.32016/12/04张调去掉部分接口V1.42017/5/24袁豪优化部分字段说明1 文档说明1.1. 文档概述 分期业务的发展极大的拓宽了商户及消费者的购物消费范围，通联商务为消费者提供合适的分期消费支付途径。1.2. 文档范围本文档描述了通联商务合作商户如何接入通联商务在线支分期付系统，拓展商户支付合作渠道。1.3. 阅读对象需要接入通联商务的合作商户及相关技术人员。2 增加商户1.

2、需要或请求接入在线支付系统的商户首先必须成为通联商务合作商户。2. 新商户的接入请参考合作商户增加相关规定。3 商户准入1. 开通权限：已成为合作伙伴的商户需要有通联商务服务人员为商户开通在线支付功能权限2. 签发密钥证书：为商户签发数据传输过程中所需密钥证书4 数据请求在线支付接口数据传输使用HTTP(或HTTPS)协议，商户提交的数据使用POST的方式提交到通联商务支付网关。12344.1 HTTP请求POST方式/*post向服务器请求数据*/HttpPost request = newHttpPost(url);StringEntity se = newStringEntity(Jso

3、nUtil.toJson(map), UTF-8);se.setContentType(application/json);request.setEntity(se);HttpResponse response = newDefaultHttpClient().execute(request);/*TODO 获取响应报文*/说明：请求的数据格式为jsonurl：请求地址map：请求参数集合，包括系统级参数和业务级参数。4.2 关键信息加密1. 根据通联商务提供的DES加密密钥，对需要传递关键信息进行加密，加密后用BASE64算法编码作为传输的值。算法：RESULT = BASE64(DES(S

4、OURCE,DESKEY)2. DES加密源码示例（以Java为例），入下：5 异常错误.5.1. 简介通联商户开放平台的接口的定义了标准的异常处理机制，所有请求除交易成功的报文，返回的其他都是异常错误报文；合作伙伴获取错误报文内的编码进行业务处理5.2. 错误报文分类接入层面分成两级：开放平台错误和业务系统错误。5.3. 错误报文示例 error_response: sub_msg: 缺少必要的参数:产品编号, args: arg: value: 4A907CB2AD13EA7B1EAD8B41E325C05D, key: sign , value: 201507271738

5、41, key: timestamp , value: 1, key: v , value: 9515600010000000110,9515600010000000011, key: card_ids , value: acctapi, key: app_key , value: allinpay.ppcs.cardinfobatch.get, key: method , value: 1, key: sign_v , value: json, key: format , res_timestamp: 20150727173845, code: 50, sub_code: missing-p

6、arameter:product_id, msg: 缺少必选参数, res_sign: 2A4E709451857FC7C3680CD9A58A6721 5.4. 错误报文处理方式合作伙伴根据返回的错误，如果有code、msg、sub_code、sub_msg不为空，则进行错误流程处理5.5. 开放平台错误平台级错误参数，主要是验证参数的是否为空，合法性，以及接入安全的校验等；50以内的为接入平台的错误，50以上的为业务平台的父级错误。接入平台错误只返回code和msg，不返回sub_code和sub_msg错误码 错误描英文 错误中文 解决方案 9Http Action Not Allowe

7、dHTTP方法被禁止请用大写的POST或GET，如果有图片等信息传入则一定要用POST才可以10Service Currently Unavailable服务不可用接口暂停或不能使用11Insufficient ISV Permissions合作伙伴权限不足应用没有权限调用该接口的权限12Remote Service Error远程服务出错API调用后端服务出错 21Missing Method缺少方法名参数传入的参数加入method字段22Invalid Method不存在的方法名传入的method字段必需是你所调用的API的名称，并且该API是确实存在的23Invalid Format无效

8、数据格式传入的format必需为json或xml中的一种24Missing Signature缺少签名参数传入的参数中必需包含sign字段25Invalid Signature无效签名签名必需根据正确的算法算出来的28Missing App Key缺少AppKey参数传入的参数必需包含app_key字段29Invalid App Key无效的AppKey参数传入的参数必需包含正确的app_key字段30Missing Timestamp 缺少时间戳参数传入的参数中必需包含timestamp参数31Invalid Timestamp 非法的时间戳参数时间戳，格式为YYYYMMDDhhmmss，例

9、如：2011010101010132Missing Version缺少版本参数传入的参数中必需包含v字段33Invalid Version非法的版本参数用户传入的版本号格式错误，必需为数字格式, 用户传入的版本号没有被提供34Missing Signature Version缺少签名版本号传入的参数中必需包含 sign_v字段，签名版本号35Invalid Signature Version非法的签名版本号传入的sign_v必须为存在。如1,2,3,4 36Missing order id此交易的支付流水号order_id不能为空必须要交易订单的API,此交易的支付流水号order_id不能为

10、空37Invalid order id同一交易支付流水号，order_id已存在，请勿重复提交同一交易支付流水号，order_id已存在，请勿重复提交50missing-parameter缺少必选参数API文档中设置为必选的参数是必传的，请仔细核对文档51invalid- parameter非法的参数参数类型不对，例如：需要传入的是数字类型的，却传入了字符类型的参数52error-parameter参数错误请求的参数经验证后不合法，如卡号不存在53business-error远程服务业务错误一般是系统对正常业务处理的限制引起的，如卡密错误5.6. 业务系统错误业务平台的的错误主要为应用服务端的

11、各种异常返回。父级错误码为50以上；主要分层四大类错误：缺少必选参数(50)，非法的参数(51)，参数错误(52), 远程服务业务错误(53)；业务平台返回错误码包括：code、msg、sub_code、sub_msg6 数据加密及签名1. 准备请求数据，所有的参数，包括系统参数（除sign字段外）和业务参数都需要参与签名。其中业务参数若有参数值为空的，不参与签名。2. 将所有需要签名的参数，按照参数名称自然升序进行排序。例如：请求参数foo=1，bar=2，baz=3排序为bar=2，baz=3，foo=1。3. 根据顺序依次连接参数名称和参数值：key + valuekey + value

12、，形成待签名字符串。则步骤1中的例子参数名和参数值连接后，得到拼装字符串bar2baz3foo1即为待签名字符串。以下实例只体现逻辑,使用appkey=test输入参数为：method=allinpay.card.cardinfo.gettimestamp=20110312192443format=xmlapp_key=testv=1.0card_id=8686860211000000516password=11111hhhhhhxxx按照参数名称升序排列(自然顺序)：app_key=test card_id=8686860211000000516 format=xml method=alli

13、npay.card.cardinfo.getpassword=11111hhhhhhxxxtimestamp=20110312192443v=1.0拼装字符串，连接参数名与参数值，例如：app_keytestcard_id8686860211000000516methodallinpay.card.cardinfo.getpassword11111hhhhhhxxxtimestamp20110312192443v1.07 技术对接1. 在线分期消费据接口以下为请求数据示例：名称类型最大长度必填可更改描述app_keyString15是OpenAPI分配给应用的AppKey 通联商务提供meth

14、odString30是接口方法名称 通联商务提供allinpay.order.orderinstall.addtimestampString14是时间戳，24小时制，格式为yyyyMMddHHmmss例如：20110125150101与通联商务当前服务器时间之差30分钟之内vString5是版本号，目前默认值：1.0 通联商务提供sign_vString5是签名版本号，目前默认值：1 通联商务提供formatString5是 可选，响应数据格式：xml或json，默认jsonmer_idString20是商户号：商户在通联商务注册的认证号码channelString2是支付渠道：0：pc 1：

15、wap；wap需要使用手机端浏览器order_idString12-20是订单号：商户生成的订单流水号，应保证易于标识或识别，字母或数字组合，不能有特殊字符，如：类型 时间 等,保证每个订单号唯一，每个订单号无论交易成功、失败或者中途关闭，只能使用一次amountString15是订单金额:应保留两位小数，且无逗号分隔，60020000（生产环境会不同）trade_dateString8是订单发生日期 yyyyMMddtrade_timeString6是订单发生时间 HHmmss, 24小时制与通联商务当前服务器时间之差30分钟之内nperString2是分期期数：6或者12或者24，分别对应

16、6期、12期、24期；生产环境会根据商户需求配置pdnoString4是产品编号:固定值 0200descriptionString200否产品名称或描述commentString200否备注return_urlString200否支付成功或失败后返回商户的页面，只是跳转，不带参数notify_urlString200是支付成功或失败后异步通知的商户URL地址，只发送参数，详情见7.4creditNameString40否持卡人姓名，一般由客户填写cetitypeString2否消费者证件类型（01：身份证）idnoString18否消费者证件号码，一般由客户填写 传输过程中需要关键数据加密p

17、honeNoString11否银行预留手机号码，一般由客户填写 传输过程中需要关键数据加密creditNoString16否消费者支付银行卡卡号，一般由客户填写 传输过程中需要关键数据加密validty_periodString4否信用卡有效期，一般由客户填写 格式 MMyy 传输过程中需要关键数据加密cvvString3否信用卡CVV2 通常3位数字，一般由客户填写 传输过程中需要关键数据加密relatePhoneString11否联系手机号 区别于银行预留手机号 两者可相同 传输过程中需要关键数据加密relate_addrString200否联系地址goods_typeString1否商品

18、类别 0：实物类 1：虚拟类商品insur_codeString30否保单号cosign_nameString30否收货人姓名cosign_phoneString11否收货人手机号 传输过程中需要关键数据加密cosign_addressString200否收货地址expressString15否快递公司express_codeString30否快递单号ext_infoString200否补充信息unalterString100否不可更改的字段名，即从接口传入的字段在页面上不可更改；多个字段以逗号分隔，字段若为不可更改则必填例：nper,creditName 表示分期期数和持卡人姓名不可更改si

19、gnString是以上所有属性请求数据签名结果，使用RSA证书签名算法注：其中sign属性为以上所有属性(除sign外)所有数据排序后使用通联商务签发证书RSA加密算法进行的签名。该签名数据将保证数据传输过程中数据完整性验证。身份证号、手机号、银行卡号需要使用商户与通联商务事先约定密钥通过DES加密，且签名数据项sign需要加密后的数据做签名。加密方法请参考 4.2单元。默认情况客户可以在页面上选择期数（即使报文里传了期数），目前有两种方案：1.将期数设为不可更改，即在参数中增加unalter，值为字符串nper2.如果不限制期数选择，那需要在接收通知的时候，再更新一下商户的订单信息（分期金额

20、，期数等），这样两边的订单信息才能一致请求方式描述由于使用了http协议进行数据传输，且传输完成后用户将接收到通联商务在线支付页面，如下：支付请求用例：报文生成请参考最后章节测试说明请求报文示例：input type=hidden name=notify_url id=notify_url value=input type=hidden name=return_url id=return_url value=document.all.pay_form.submit();正确报文返回：用户获得分期消费页面，如下：7.1-1PC端支付页面7.1-2 手机端支付页面2. 订单状态查询接口 接口参数说

21、明名称类型最大长度是否必需描述app_keyString15是OpenAPI分配给应用的AppKey 通联商务提供methodString30是接口方法名称 通联商务提供allinpay.order.orderinstall.querytimestampString14是时间戳，24小时制格式为yyyyMMddHHmmss例如：20110125010101 与通联商务当前服务器时间之差30分钟之内vString5是版本号，目前默认值：1.0 通联商务提供sign_vString5是签名版本号，目前默认值：1 通联商务提供formatString5是可选，响应数据格式。xml或json 默认js

22、onmer_idString20是商户号：商户在通联商务注册的认证号码order_idString是订单id 支持多个订单id查询 以逗号分隔signString是以上所有属性请求数据签名结果，使用RSA证书签名算法请求示例： TreeMap map = new TreeMap();map.put(v, 1.0);map.put(app_key, testhn);map.put(format, json);map.put(sign_v, 1);map.put(timestamp, sdf.format(new Date();map.put(method, allinpay.order.orde

23、rinstall.query);/业务参数map.put(mer_id, 999290053990002);map.put(order_id, 201609271648581380);try String keyPath = D:/private.pfx;String privatePwd = 123456;PrivateKey privateKey = RsaUtil.loadPrivateKey(keyPath, privatePwd);TreeMap queryMap =RsaSign.addSign(map, privateKey);String result = HttpUtils.

24、doPost( queryMap);System.out.print(返回信息：-+result); catch (Exception e) / TODO Auto-generated catch blocke.printStackTrace();报文返回示例： order_info_response: res_timestamp: 20161202110225, res_sign: 64328AA7A4242690BD73E72C88B99CE2BE6549EB1800AFC6E49931C39471CC90FC93A4DB7D26006FC004496ACE82CC74B920DAE131

25、49319889C3DDDC9F8CF65B4EB31DCA94E4FC92AC022480350FCF7A2E32E70CD3E221D47A7359528EA1D6590EDBE96FAC6CB99C3761A4E7D6FF8C0F1807E5AE0D84BEB6104ACD60F4AACB09, map: entry: key: 201609271648581380, value: 3 其中KEY为支付流水号，value为订单状态：0: 待支付 1: 支付成功 2: 支付失败 3: 订单失效4: 退货待审批5: 退货成功6: 撤销成功111: 支付流水号为空，查无此项错误报文示例： er

26、ror_response: sub_msg: 缺少必要的参数:查询的订单列表为空或商户号为空, args: arg: value: 20161202111652, key: timestamp , value: 23807953bd42ab11119940e2f5cb31a1c93c0a56b8b4cf25754664b2e9007fb0dc584f7f9cfe90c2b79c0838eb767bb9796889556676ae5ba751710da4b3143a5c77cd90fc8fd83b96f6d8cdedce56b54d97b0d68efafd69c6d8c3762d3873b5db

27、d0c08dfadf768127ef7f38d6c767753195dda6ca8af1359a8a96cb63928c83, key: sign , value: 1, key: v , value: 999290053990002, key: mer_id , value: 1, key: sign_v , value: allinpay.order.orderinstall.query, key: method , value: testhn, key: app_key , value: json, key: format , value: , key: order_id , res_t

28、imestamp: 20161202111652, code: 50, sub_code: missing-parameter:orderId, msg: 缺少必选参数 , res_sign: 440C4BBEA71A2DE8A4AEEA888C490541337618EC94C1969B4D9FD7EB27F8C74FA0AE8B55D3DC01F3C9EDDA4B2C37560539512F75CCE71715BD8625D5DD3815BA95D7A352DE008BDE04569895A9B227E4892E7C61B504DFE9A38E05171CB08DF261EB9BCE5B3

29、1304AF30808916F96A01524449160EFE6D5B66B575A9A347FA73F 3. 订单退货申请提交接口 接口参数说明名称类型最大长度是否必需描述app_keyString15是OpenAPI分配给应用的AppKey 通联商务提供methodString30是接口方法名称 通联商务提供allinpay.order.orderinstall.refundtimestampString14是时间戳，24小时制格式为yyyyMMddHHmmss例如：20110125150101 与通联商务当前服务器时间之差30分钟之内vString5是版本号，目前默认值：1.0 通联商

30、务提供sign_vString5是签名版本号，目前默认值：1 通联商务提供formatString5否可选，响应数据格式。xml或json 默认jsonmer_idString20是商户号：商户在通联商务注册的认证号码order_idString12-20是订单号，需要与支付成功时的订单号一致amountString15是订单金额:应保留两位小数，且无逗号分隔，需要与支付成功时的订单金额一致channelString2是支付渠道：0：pc 1：wap，需要与支付成功时的支付渠道一致trade_dateString8是订单发生日期 yyyyMMdd，需要与支付成功时的订单日期一致trade_ti

31、meString6是订单发生时间 HHmmss，需要与支付成功时的订单时间一致pdnoString4是产品编号:固定值 0200signString是以上所有属性请求数据签名结果，使用RSA证书签名算法请求示例：同订单查询接口报文返回示例： sucess_business_response: res_timestamp: 20170106154047, res_sign: 14DCB4421911131D51E529BBE98950454BC857733F51175AEB7F756BBFBDA58490C7468DAFC94A456CC03E1B75A621F320BD8053573A5AAF

32、6E38BF172F61B64CB37DABD83B563DEA258D73F73AF615C16B4A3001281DCC2A3C2D15CDEAD57D26A79514962C5FC3B55888A197EE36E2C40AF4CC479233BE2D4B80FB7E912FB042, code: 0, msg: 退货申请提交成功 错误报文示例：同订单状态查询接口4. 商户通知 商户通知为通联商务通过商户上传的 notify_url 地址发起http请求，将商户订单的支付状态发送至商户。商户收到请求后返回指定的字符串用以表明收到通知请求。商户通知为异步发起的请求，一共会发送5次，期间如收到

33、商户返回的字符串“success”则停止发送。订单状态： 0 : 待支付 1：消费成功 2 消费失败 3：订单失效 4：订单提交失败“消费成功”通知报文:msg=消费成功nper=12orderId=201608301002296995result=1totalAmt=766.00sign=3e38273f1c38d964246a9b1d204da9c739874c894a15edd4c51aa02e79dae772565ab1961626e49e7cf402c1091d75a9e62c345dca8037c9b2e9fdc793e50809b5b00913b8f12894745ae6577e

34、f7599f93b7269cd27a4a22cfa0e8363267d5747a00e8fd7a048065a7b56b5e5b194d08fab6db3f04114224b0d66fb748931fcc“消费失败”通知报文:msg=订单消费失败nper=12orderId= 20170607115145result=2totalAmt=766.01sign= 884ab172a8c0f3e169b8d3c19363daf73c72496de979e623b4b76ae8279a32b48deb2ff30f8bf077e802edc826ff60c67ae772d3cc1d51189e88ee

35、cd8f5202334d6ba6152a5afd4daac07e8b93009e7e3eaac67d44e5bf50340b574846957c375f17608fe8b7dcf76d8f52e30cf872da381253cc1670f11b907a35ff5e038ada “订单失效”通知报文:msg=该笔订单失效orderId= 20170707129496715343result=3sign= 6f86849487f93bdca2cebb1cb099a9880ed654e97bae1d2e9986c037e8b466317d2b4534b1d351cedf35b03deb9bd3e44b2805d3b5d9e25673a2949582ed0140b3f92b43ce6d71b8757e8b8f5a412435fe1e52b685c57f900cb9dfbc010b08b05d84fb3035cb0b873662120eb5bd2e82439b8f9e9ed4431c801d2038a607a3f0注：商户通知中的签名用于保证商户接收数据的安全，签名方式同上商户使用通联商务发放的公钥证书做数据验证。因通知中的字段不定，接收报文时建议使用Map request