接入必看

开始接入

温馨提示：阅读本文档之前，请认真仔细的确认您已经执行了下面的三步操作，并获得了有效的扫呗接入资料：

签订合作协议。
联系业务BD提交扫呗内部接口对接申请。
开发人员与扫呗技术支持建立联系。
联系业务或者BD同事，提交资料进行商户开户。
对接支持同事基于正式商户映射测试商户，或提供其它对接测试参数。

测试环境准备

⑴测试服务地址

具体测试地址以对接支持同事邮件内提供的地址为准。

⑵测试账号

测试账号统一由我司技术同学分配。因支付需要真实扣款，若对接的是支付接口，需先联系业务同事或者项目运营同事，创建商户同主体的正式商户后，才能提供测试商户。

对接商户接口需以下参数：
- 机构号inst_no
- 令牌key
对接支付接口需以下参数：
- 商户号merchant_no
- 终端号terminal_id
- 令牌access_token

拿到测试环境后，合作方即可进入测试联调阶段，有问题可在相关对接群中咨询技术同学，由于支持群较多，在咨询问题时，最好是@对应对接支持同事。

对接测试辅助工具

测试工具页：http://test2.lcsw.cn:8117/demo/

使用该页面设置好商户号、终端号、终端密钥，可测试接口的调用，查看请求报文、返回报文、请求签名串等，常用工具中还可拼接字典序签名串。字典序通用请求中，可请求字典序的接口，获取签名串。

注意：如果是正式环境商户信息，注意将接口地址切换到正式。

生产环境

注意：接口联调必须先在测试环境联调，由技术同学验收通过后，才可正式接入线上生产环境。

生产环境账号参数：由商务或运营同事提供

生产环境域名：统一由技术同学提供

以上资料在测试环境中和生产环境中并不相同，准备调试和切换环境时请认真核对并确认无误。

开通支付通道

微信公众号
合作商如需对接公众号支付接口，需提供微信应用ID（AppID）、应用密钥（AppSecret）以及支付授权目录，在相关参数配置完毕后，再联系扫呗技术人员，获取测试商户号、测试终端号以及测试接口域名。
QQ钱包
合作商如需使用QQ钱包支付通道，需要提供QQ钱包商户号、QQ钱包key、QQ钱包证书密码以及QQ钱包退款密码，在后台配置好相关参数后，方可开通QQ钱包支付通道。
京东钱包
合作商如需使用京东钱包支付通道，需要提供京东钱包商户号、京东钱包密钥，在后台配置好相关参数后，方可开通京东钱包支付通道。
微信及支付宝的刷卡支付、扫码支付
合作商如需对接微信、支付宝的预支付、扫码支付的接口，可直接联系扫呗技术人员，获取测试商户号、测试终端号以及测试接口域名。

通信协议

本文档中的所有接口，未明确说明的，均采用HTTP标准通信协议，请求和响应的Content-type均为application/json，字符编码统一为UTF-8。

注："商户回调通知"接口、"交易通知"接口、"交易实时同步"接口Content-type为text/xm。

签名算法

httpclient方式发起的接口请求，请求和接收数据均需要校验签名。签名测试工具

拼接串说明：接口中每一个字段(key_sign字段除外),以字典顺序(字母顺序)排序之后,按照a=value1&b=value2.....&令牌标识="密钥"的顺序,进行拼接。对得到的字符串进行MD5签名/验签；

示例请求参数：

{
"pay_ver": "201",
"pay_type": "010",
"service_id": "010",
"merchant_no": "839305812000286",
"terminal_id": "30616969",
"device_no":"202011261843460000",
"terminal_trace": "201811231154130000",
"terminal_time": "20181123115413",
"auth_no": "xxxxxxxx",
"total_fee": "1",
"order_body": "",
"attach": "",
"goods_detail": "",
"key_sign": ""
}

对应签名串：
string1="attach=&auth_no=xxxxxxxx&device_no=202011261843460000&goods_detail=&merchant_no=839305812000286&order_body=&pay_type=010
&pay_ver=201&service_id=010&terminal_id=30616969&terminal_time=20181123115413&
terminal_trace=201811231154130000&total_fee=1" ；

❗特别注意：

赋值的空字符串需参与签名；如"attach": ""，需要拼接&attach=&

接口中包含terminal_id(终端号)字段的，令牌标识为access_token，待签名字符串格式:string2=string1+"&access_token=终端密钥";

接口中包含inst_no(机构号)字段的，令牌标识为key，待签名字符串格式: string2=string1+"&key=机构密钥";

通过MD5取得签名字符串: key_sign=md5(string2)

JAVA-SDK

SDK下载

SDK文件：java-sdk-1.2.1

SDK引入方式参考

方式一：IDEA或者Eclipse引入本地jar包的方式。具体操作可网上搜索对应开发工具添加jar包的步骤。
方式二：使用maven的方式，将jar包安装到本地仓库后，通过pom引入，具体步骤和maven命令请自行网上搜寻。

//请自行根据电脑系统类型修改-Dfile指定的jar包所在路径格式，注意将命令中的-Dversion指定的jar包版本换成所下载的版本
mvn install:install-file -Dfile=D:\saobei-open-sdk-1.2.1.jar -DgroupId=com.lcsw.opensdk -DartifactId=saobei-open-sdk -Dversion=1.2.1 -Dpackaging=jar
//安装到本地仓库后，在pom中添加如下引入，注意version修改成所安装的版本号
<dependency>
    <groupId>com.lcsw.opensdk</groupId>
    <artifactId>saobei-open-sdk</artifactId>
    <version>1.2.1</version>
</dependency>

方式三：在pom.xml文件中，你可以使用dependency标签的systemPath属性来指定本地JAR包的路径，maven具体操作可自行网上搜索。

//version注意换成所使用的版本，systemPath换成jar所在目录
<dependencies>
  <dependency>
    <groupId>com.lcsw.opensdk</groupId>
    <artifactId>saobei-open-sdk</artifactId>
    <version>1.2.1</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/saobei-open-sdk-1.2.1.jar</systemPath>
  </dependency>
</dependencies>

工具类

❗特别说明：

SDK主要提供工具类，便于对请求参数进行签名或者返回参数验签。

SDK内有部分接口的实体类，若在SDK内没找到对应实体类，请自行定义实体类。

若SDK内存在的实体类字段与接口内字段不一致的，可自行创建子类定义属性，并继承原实体类。

注：目前只提供java语言的SDK,其它开发语言请自行按照签名算法要求进行拼接签名

ApiUtil工具类：主要提供构建请求参数和返回参数，可自动进行签名和验签。

//构造请求参数并对报文自动加签，t为设置好请求参数的实体对象。使用了该方法，不需要再使用SignBeanUtil工具类进行签名
JSONObject request = ApiUtil.convertRequest(t,"填机构密钥或者终端密钥","填令牌标识，请看《签名算法》章节-特别注意-的说明");

//转换返回（或回调）参数并对报文自动验签，response为接口返回参数，t为创建好的返回参数接收对象。使用了该方法，不需要再使用SignBeanUtil工具类进行签名
t = ApiUtil.convertResponse(response,t,"填机构密钥或者终端密钥","填令牌标识，请看《签名算法》章节-特别注意-的说明");

SignBeanUtil工具类：主要提供参数的字典序排序后的签名方法。

//参数签名方法，若使用了ApiUtil工具类的封装参数方法，无需使用该方法在签名。t为请求参数，key_sign和utf-8为固定字符串不用修改。
SignBeanUtil.FilterNullSign(t, "填令牌标识，请看《签名算法》章节-特别注意-的说明","填机构密钥或者终端密钥", "key_sign", "utf-8");

HttpClientUtil工具类：主要提供post请求方法。

//serviceUrl为接口完整url地址，request为请求参数（可用ApiUtil工具转换请求参数），timeout为接口超时时间（单位ms），response为返回参数（可用ApiUtil工具转换成返回实体）
String response = HttpClientUtil.post(serviceUrl,JSON.toJSONString(request), timeout,"application/json","utf-8");

通用方法

以下方法，可应用与所有post请求，且使用字典序签名的接口。方法内会自动进行签名，故不需要为接口中的key_sign字段赋值。

OpenParameters.Builder builder=new OpenParameters.Builder();
builder.apiName("接口地址");//对应接口上的url部分地址，如/pay/open/query
builder.apiUrl("接口域名");//请使用对应接口域名，将和apiName拼接成完整接口地址。如http://www.lcsw.cn/lcsw
builder.param(json.toString());//按照接口字段要求为实体对象属性赋值后转json并toString。
OpenParameters openParameters = builder.build();//实例化对象
//创建client
SaobeiApiClient client = new DefaultSaobeiApiClient<>("终端密钥或机构密钥");
String execute = client.execute(openParameters);//返回参数已自动进行了验签

警告

密钥是一个非常重要的数据，请您必须小心谨慎的确保此数据保存在足够安全的地方。您从扫呗官方获得此数据的同时，即表明您保证不会被用于非法用途和不会在没有得到您授权的情况下被盗用，一旦因此数据保管不善而导致的经济损失及法律责任，均由您独自承担。

开发指引

API