设备接入第三方支付系统说明文档 (二维码支付) V2.4 版本 日期 编写人 描述 V1.0 2017.11.6 初版 V1.1 2017.11.17 修改 sign V1.2 2018.1.18 修正通信链路 V1.3 2018.3.27 增加和修改安全机制 V1.4 2018.03.28 增加第三方订单 ID V1.5 2018.03.30 修正 APPKEY V1.6 2018.04.28 增加第三方积分支付接口 V1.7 修正文档结构 V1.8 2018.09.15 修正第三方支付方式 V1.9 2018.11.06 32 到 39 定义为第三方支付,默认使用 36 V2.0 2018.11.10 获取第三方支付接口二维码时增加商品原价格 V2.1 2019.01.05 修正部分描述 V2.2 2019.10.25 修改部分文字描述 V2.3 2022.02.26 增加示例 V2.4 2023.08.29 优化说明、增加业务流程 目录 1.概述 .......................................................................................................................................................... 3 2.名词解释 .................................................................................................................................................. 3 3.通信方式 .................................................................................................................................................. 3 4.接口说明 .................................................................................................................................................. 4 4.1 获取第三方付款码 ...................................................................................................................... 4 4.2 轮询支付结果接口 ....................................................................................................................... 5 4.3 出货成功或失败通知接口 ........................................................................................................... 5 5.鉴权方法 .................................................................................................................................................. 6 6.业务流程 .................................................................................................................................................. 7 1.概述 此文档针对合作单位可以根据具体业务需求进一步开发。此文档在没有经过双方公司的 确认同意的情下，不得对外发布。 2.名词解释 取货码 取货码是一串数字 weburlA 服务商的 web 二维码验证接口 API 接口地址 weburlB 服务商的 web 销售成功通知接口 API 接口地址 weburlC 服务商的 web 获取支付结果 API 接口地址 machid 设备 ID(11 位字符) 例:99999999999 twocode 二维码数据(不是图片) trackno 轨道编号(10 到 69 或其它轨道标识号)实际与售货机货盘轨道数对应 咖啡机和饮料机从(01 开始) orderid 订单号 小于 60 位字符 torderid 第三方订单号 建议不使用 特殊需要时可用 3.通信方式 ➢ 字符集：UTF-8 ➢ 采用 http 或 https，post 的方式，入参格式为 Key-Value ➢ 自动售货机 ->运营商的服务器 售 运营商 货 服务器 机 (C) (A) 售货机：A 端 运营商服务器：C 端 4.接口说明 4.1 获取第三方付款码 请求网址 传递参数（A 端----> C 端） 返回值 http://weburlA ver=v1(接口版本号) {"orderid":"原值返回","torderid":"第三方 orderid=订单号（小于 60 系统 ID","code":"0","msg":"消息内容 位） ","twocode":"lksajfddkjdsflsjfsalkj"} machid=机器设备 ID 号 trackno=轨道编号 code( 0 表示失败,失败时需要返回 msg name=商品名称(UTF-8) 1 表示成功处理) price=价格(设置价*100) twocode:二维码数据(不是图片) channelid=36 ( 33:第三方支 付 34:第三方支付 35:第三方支付 36:第三方支付(默认) 37:第三方支付 38:第三方支付 39:第三方支付 ) randstr=随机的字符串 timestamp=201803271343 sign=认证签名 sign 认证请参考下面章节的 鉴权方法 正式环境地址： 请求示例(Key-Value)： "ver": "v1", "orderid": "0000000000722022615564401910140", "machid": "00000000007", "trackno": "15", "name": "可乐", "price": "400", "channelid": "36", "randstr": "pt9fygnwg68a6ktc", "timestamp": "20220226155645", "sign": "89fb5b7e3b319c57a4ca52bb0687565b862e39e3" 返回示例： { " code": "1", "orderid": "0000000000722022615564401910140", "torderid": "00000000007", "msg": "成功", "twocode": " http://xxx/advertise.html?orderid=0000000000722022615564401910140&advurl=https://qr .alipay.com/bax008886cy0lui4taof2570&goodsprice=0.01 " } 4.2 轮询支付结果接口 请求网址 传递参数（A 端----> C 端） 返回值 http://weburlC ver=v1(接口版本号) {"orderid":"原值返回 orderid =订单号 ","torderid":"123","code":"0","msg":"消息 torderid=订单号(第三方 ID) "} machid=机器设备 ID 号 channelid=渠道 id code :0 表示失败，失败时需要返回 msg randstr=随机的字符串 code :1 消费者付款成功 timestamp=201803271343 code :2 正在等待消费者付款 sign=认证签名 code :3 表示此次交易已过期 code :4 表示此次交易已关闭 code :5 表示此次交易已完成 sign 认证请参考下面 章节的 鉴权方法 交易有效时间由第三方设置,请求方在没有消费者主动退出付款界面的情况下,可以设置 1-5 分钟的等 待时间 4.3 出货成功或失败通知接口 请求网址 传递参数（A 端----> C 端） 返回值 http://weburlB ver=v1(接口版本号) {"orderid ":"原值返回 orderid =订单号（小于 60 位） ","torderid":"123","code":"0","msg":" torderid=订单号(第三方 ID) 消息内容"} machid=机器设备 ID 号 trackno=轨道编号 status=0 或 1 code:( 0 表示失败,失败时需要返回 msg (0 出货失败 1 出货成功) 1 表示成功处理) errinfo=错误信息(UTF-8) randstr=随机的字符串 timestamp=201803271343 sign=认证签名 sign 认证请参考 下面 章节的 鉴权方法 5.鉴权方法 为了防止接口被恶意调用，服务器需要对向接口传输的数据进行校验，具体方法如下： 1、每台机器，都会被分配一个 id（称为 machid）和一个密钥（appkey），密钥为一个字符 串，由 16 个大小写字母或数字组成，不同机器的 machid 和密钥不一样，可以出厂前 define 在代码中或是写在配置文件中。 2、调用任何接口时都要额外传输以下三个参数： randstr：随机的字符串，同样由 16 个大小写字母或数字组成，每次调用接口都应该重新生 成。 timestamp：机器本地 Unix 时间戳，与全球标准时间的误差不要超过 2 分钟。 sign：签名，生成方法如下： 1）将 appkey、timestamp、randstr 三个参数进行字典序排序 2）将三个参数字符串拼接成一个字符串进行 sha1 加密 下面是一个示例，以机器请求产生订单为例，POST 的参数为： appkey 1234567890abcdef(默认值) randstr ok76oc1jkh2sy85o timestamp 20190105144625 sign 81fd6a8d97e3b775828028371a0cc85d6678d39a 先将 appkey、timestamp、randstr 三个参数进行字典序排序，得到字符串 1234567890abcdef 20190105144625 ok76oc1jkh2sy85o 然 后 对 这 个 字 符 串 进 行 sha1 加 密 ， 得 到 最 终 签 名 81fd6a8d97e3b775828028371a0cc85d6678d39a 6.业务流程 开始 用户点击商品 进入支付界面， 获取二维码(4.1 接口) 用户支付， 售货机查询支付结果 （4.2 接口） 否 是 支付成功？ 开始出货 是 否 出货成功？ 出上报出货结果 上报出货结果 (4.3 接口) (4.3 接口) (建议退款) 结束