接入指南

开始接入

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

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

测试环境

⑴**测试服务地址**

首选，测试环境地址：

支付接口地址：http://test.lcsw.cn:8045/lcsw/+相关API接口URL

商户接口地址：http://test.lcsw.cn:8045/lcsw_mch/+相关API接口URL

备用域名http://test2.lcsw.cn:8117，8045和8117端口的两个地址，若其中一个有问题，就换另一个地址试下。

⑵**测试账号**

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

商户系统：
- 机构号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。

接口的完整URL由统一前缀+接口的URL组成，测试环境和生产环境的统一前缀完全不同，测试环境的URL前缀为http://test.lcsw.cn:8045/lcsw。

例如测试环境下创建商户接口的完整URL为http://test.lcsw.cn:8045/lcsw_mch/merchant/100/add。生产环境的统一前缀在测试环境调试通过以后，从扫呗的技术支持处获得。

签名算法

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

拼接串说明：

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

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

示例请求参数：

{
"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" ；

支付2.0待签名字符串格式: string2=string1+"&access_token=终端密钥";

其它接口待签名字符串格式: string2=string1+"&key=机构密钥";

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

警告

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

验证密码规则

支付金额>1000元的交易需要验证用户支付密码
用户账号每天最多有10笔交易可以免密，超过后需要验证密码
微信支付后台判断用户支付行为有异常情况，符合免密规则的交易也会要求验证密码
注：基于一定的风控策略，存在随时需要验密的可能性。

开发指引

API