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

小通分期商户接入手册

通联商务

2016年8月

1文档说明

1.1.文档概述

分期业务的发展极大的拓宽了商户及消费者的购物消费范围，通联商务为消费者提供合适的分期消费支付途径。

1.2.文档范围

本文档描述了通联商务合作商户如何接入通联商务在线支分期付系统，拓展商户支付合作渠道。

1.3.阅读对象

需要接入通联商务的合作商户及相关技术人员。

2增加商户

1.需要或请求接入在线支付系统的商户首先必须成为通联商务合作商户。

2.新商户的接入请参考合作商户增加相关规定。

3商户准入

1.开通权限：已成为合作伙伴的商户需要有通联商务服务人员为商户开通在线支付功能权

限

2.签发密钥证书：为商户签发数据传输过程中所需密钥证书

4数据请求

在线支付接口数据传输使用HTTP(或HTTPS)协议，商户提交的数据使用POST的方式提交

到通联商务支付网关。

4.1HTTP请求POST方式

/*post向服务器请求数据*/

HttpPost request = new HttpPost(url);

StringEntity se = new StringEntity(JsonUtil.toJson(map), "UTF-8");

se.setContentType("application/json");

request.setEntity(se);

HttpResponse response = new DefaultHttpClient().execute(request);

/*TODO 获取响应报文*/

说明：请求的数据格式为json

url：请求地址

map：请求参数集合，包括系统级参数和业务级参数。

4.2关键信息加密

1.根据通联商务提供的DES加密密钥，对需要传递关键信息进行加密，加密后用BASE64

算法编码作为传输的值。

算法：RESULT = BASE64(DES(SOURCE,DESKEY))

2.DES加密源码示例（以Java为例），入下：

5异常错误

5.1.简介

通联商户开放平台的接口的定义了标准的异常处理机制，所有请求除交易成功的报文，返回的其他都是异常错误报文；合作伙伴获取错误报文内的编码进行业务处理

5.2.错误报文分类

接入层面分成两级：开放平台错误和业务系统错误。

5.3.错误报文示例

5.4.错误报文处理方式

合作伙伴根据返回的错误，如果有code、msg、sub_code、sub_msg不为空，则进行错误流程处理

5.5.开放平台错误

平台级错误参数，主要是验证参数的是否为空，合法性，以及接入安全的校验等；50以内的为接入平台的错误，50以上的为业务平台的父级错误。接入平台错误只返回code和msg，不返回sub_code和sub_msg

5.6.业务系统错误

业务平台的的错误主要为应用服务端的各种异常返回。父级错误码为50以上；

主要分层四大类错误：缺少必选参数(50)，非法的参数(51)，参数错误(52), 远程服务业务错误(53)；

业务平台返回错误码包括：code、msg、sub_code、sub_msg

6数据加密及签名

1.准备请求数据，所有的参数，包括系统参数（除sign字段外）和业务参数都需要参与签

名。其中业务参数若有参数值为空的，不参与签名。

2.将所有需要签名的参数，按照参数名称自然升序进行排序。例如：请求参数foo=1，bar=2，

baz=3排序为bar=2，baz=3，foo=1。

3.根据顺序依次连接参数名称和参数值：key + value…key + value，形成待签名字符串。

则步骤1中的例子参数名和参数值连接后，得到拼装字符串bar2baz3foo1即为待签名字

符串。

以下实例只体现逻辑,使用appkey=test

输入参数为：

按照参数名称升序排列(自然顺序)：

拼装字符串，连接参数名与参数值，例如：

7技术对接

1.在线分期消费据接口

以下为请求数据示例：

注：其中sign属性为以上所有属性(除sign外)所有数据排序后使用通联商务签发证书RSA 加密算法进行的签名。该签名数据将保证数据传输过程中数据完整性验证。

身份证号、手机号、银行卡号需要使用商户与通联商务事先约定密钥通过DES加密，且签

名数据项sign需要加密后的数据做签名。加密方法请参考4.2单元。

默认情况客户可以在页面上选择期数（即使报文里传了期数），目前有两种方案：

1.将期数设为不可更改，即在参数中增加unalter，值为字符串nper

2.如果不限制期数选择，那需要在接收通知的时候，再更新一下商户的订单信息（分期金额，期数等），这样两边的订单信息才能一致

请求方式描述

由于使用了http协议进行数据传输，且传输完成后用户将接收到通联商务在线支付页面，如下：

支付请求用例：

报文生成请参考最后章节测试说明

请求报文示例：

用户获得分期消费页面，如下：

7.1-1PC端支付页面

7.1-2 手机端支付页面2.订单状态查询接口

报文返回示例：

3.订单退货申请提交接口

请求示例：

同订单查询接口

错误报文示例：

同订单状态查询接口

4.商户通知

商户通知为通联商务通过商户上传的notify_url 地址发起http请求，将商户订单的支付状态发送至商户。商户收到请求后返回指定的字符串用以表明收到通知请求。

商户通知为异步发起的请求，一共会发送5次，期间如收到商户返回的字符串“success”则停止发送。

“消费失败”通知报文:

注：

商户通知中的签名用于保证商户接收数据的安全，签名方式同上

商户使用通联商务发放的公钥证书做数据验证。

因通知中的字段不定，接收报文时建议使用

Map requestMap = request.getParameterMap();

来接收参数。

5.测试说明

为了便于接入商户测试及联调方便，为开发人员准备了相应的工具类包以供调用。目前只提供java语言的实现。由于接口是基于http协议的，原则是可以提供跨语言平台的访问的。

al l i np ay-o nl i ne-1.0.j ar

使用示例：

商户将生成html页面信息通过HttpServletResponse对象返回到客户端浏览器，用户浏览器将自动请求通联商务支付网关，并将商户封装信息传入网关。

生成的html示例：