接入必看

开始接入

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

签订合作协议
提交接口帐户数据开户登记表，用于开立测试和生产环境帐户
开发人员与扫呗技术支持建立联系

测试环境

⑴测试服务地址

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

⑵测试账号

测试账号统一由我司技术同学分配。

商户接口：
- 机构号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,其它开发语言请自行按照签名算法要求进行拼接签名

SDK下载：java-sdk-1.2.1

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

//构造请求参数并对报文自动加签，t为设置好请求参数的实体对象，key为密钥值，令牌标识请看签名算法说明，使用了该方法，不需要再使用SignBeanUtil工具类进行签名
JSONObject request = ApiUtil.convertRequest(t,"key","令牌标识");
//转换返回（或回调）参数并对报文自动验签，response为接口返回参数，t为创建好的返回参数接收对象，key为密钥值，令牌标识请看签名算法说明，使用了该方法，不需要再使用SignBeanUtil工具类进行签名
t = ApiUtil.convertResponse(response,t,"key","令牌标识");

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

//参数签名，若使用了ApiUtil工具类的封装参数方法，无需使用该方法在签名。t为请求参数，令牌标识请看签名算法说明，key为密钥值，key_sign为固定字符串
SignBeanUtil.FilterNullSign(t, "令牌标识","key", "key_sign", "utf-8");

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

//serviceUrl为接口完整url地址，request为请求参数，timeout为接口超时时间（单位ms）
HttpClientUtil.post(serviceUrl,JSON.toJSONString(request), timeout,"application/json","utf-8");

警告

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

开发指引

API