1. 接入指南

1.1. 开始接入

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

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

1.1.1. 有效的扫呗接入资料：

扫呗商户系统：
- 机构号inst_no
- 令牌key
扫呗支付系统：
- 商户号merchant_no
- 终端号terminal_id

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

1.1.2. 开通支付通道

微信公众号

合作商如需对接公众号支付接口，需提供微信应用ID（AppID）、应用密钥（AppSecret）以及支付授权目录，在相关参数配置完毕后，再联系扫呗技术人员，获取测试商户号、测试终端号以及测试接口域名。
QQ钱包

合作商如需使用QQ钱包支付通道，需要提供QQ钱包商户号、QQ钱包key、QQ钱包证书密码以及QQ钱包退款密码，在后台配置好相关参数后，方可开通QQ钱包支付通道。
京东钱包

合作商如需使用京东钱包支付通道，需要提供京东钱包商户号、京东钱包密钥，在后台配置好相关参数后，方可开通京东钱包支付通道。
微信及支付宝的刷卡支付、扫码支付

合作商如需对接微信、支付宝的预支付、扫码支付的接口，可直接联系扫呗技术人员，获取测试商户号、测试终端号以及测试接口域名。

1.2. 通信协议

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

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

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

1.3. 接口安全

1.3.1. 签名

本文档中的每一个接口，未明确说明的，均在请求参数附加一个名为key_sign的参数，此参数即本次请求参数的签名字符串。举个粟子：

假设必填请求参数如下

{
    "pay_ver":"100",
    "pay_type":"010",
    "service_id":"020",
    "merchant_no":"889521000000001",
    "terminal_id":"10000001",
    "terminal_trace":"1234567890",
    "terminal_time":"20161001120010"
}

按文档中参数列表的顺序拼接参数

 string1="pay_ver=100&pay_type=010&service_id=020&merchant_no=889521000000001&terminal_id=10000001&terminal_trace=1234567890&terminal_time=20161001120010";

支付接口参数拼接顺序是文档序，商户接口的参数拼接顺序是字典序

拼接令牌

 string2=string1+"&access_token=03c3ef1574c442cd96520aa6772cb5d2";

支付接口的令牌参数名是access_token，通过注册终端接口获得；商户接口的令牌参数名是key，由扫呗人工颁发。

通过摘要算法取得签名字符串

 key_sign=md5(string2);

最后将要请求接口的参数应该是这个样子：

{
 "pay_ver":"100",
 "pay_type":"010",
 "service_id":"020",
 "merchant_no":"889521000000001",
 "terminal_id":"10000001",
 "terminal_trace":"1234567890",
 "terminal_time":"20161001120010",
 "key_sign":"bc3e6ac8355bf3a4c2cf9cd00d6065b8"
}

1.3.2. 警告

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

1.3.3. 常见问题

本文档若无特别说明的，均只有必传参数参与签名，如果不是必传参数，即使传过来也不参与签名
参数名区分大小写，key_sign参数的值不区别大小写，但是仍然建议以小写的形式发送给扫呗
本文档所有接口如未明确说明的，在return_code等于01即成功时，响应参数中都会有key_sign，客户端应当对key_sign值进行校验
返回参数中的key_sign是由所有返回参数（包括非必传参数）均参与拼接的字符串得来
除商户接口商户审核通知、支付接口交易通知在签名前加入了令牌以外，其它接口的响应参数中的key_sign均没有令牌参与签名
除支付接口中的注册终端接口本身是用来获取令牌之外，其它接口请求参数签名必须拼接令牌
测试环境中所产生的支付金额不会划入正式账号绑定的银行卡下，请勿使用测试账号测试到账与清算

接入指南