设备接入第三方支付系统说明文档 (二维码支付) 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.名词解释 +----------+-----------------------------------------------------------+ | 取货码 | 取货码是一串数字 | +----------+-----------------------------------------------------------+ | | 服务商的 web 二维码验证接口 API 接口地址 | | weburlA | | +----------+-----------------------------------------------------------+ | | 服务商的 web 销售成功通知接口 API 接口地址 | | weburlB | | +----------+-----------------------------------------------------------+ | | 服务商的 web 获取支付结果 API 接口地址 | | weburlC | | +----------+-----------------------------------------------------------+ | machid | 设备 ID(11 位字符) 例:99999999999 | +----------+-----------------------------------------------------------+ | | 二维码数据(不是图片) | | twocode | | +----------+-----------------------------------------------------------+ | | 轨道编号(10 到 69 | | trackno | 或其它 | | | 轨道标识号)实际与售货机货盘轨道数对应咖啡机和饮料机从(01 | | | 开始) | +----------+-----------------------------------------------------------+ | | 订单号 小于 60 位字符 | | orderid | | +----------+-----------------------------------------------------------+ | | 第三方订单号 建议不使用 特殊需要时可用 | | torderid | | +----------+-----------------------------------------------------------+ 3.通信方式 > 字符集：UTF-8 > 采用 http 或 https，post 的方式，入参格式为 Key-Value > 自动售货机 ->运营商的服务器 +-----------+----------------------------------------------+-----------+ | 售 | | 运 营 | | | | | | 货 | | 商服务器 | | | | | | 机 | | (C) | | | | | | (A) | | | +-----------+----------------------------------------------+-----------+ | | | | +-----------+----------------------------------------------+-----------+ | | | | +-----------+----------------------------------------------+-----------+ 售货机：A 端 运营商服务器：C 端 4.接口说明 4.1 获取第三方付款码 +-------------+------------------+-------------------------------------+ | 请求网址 | 传递参数（A | 返回值 | | | 端----> C 端） | | +-------------+------------------+-------------------------------------+ | htt | ve | {"orderid | | p://weburlA | r=v1(接口版本号) | ":"原值返回","torderid":"第三方系统 | | | | ID","code":"0","msg":"消息内容 | | | orde | | | | rid=订单号（小于 | ", | | | 60位） | "twocode":"lksajfddkjdsflsjfsalkj"} | | | | | | | | code( 0 表示失败,失败时需要返回 | | | machid=机器设备 | msg 1 表示成功处理) | | | ID | | | | 号 | twocode:二维码数据(不是图片) | | | trackno=轨道编号 | | | | | | | | name | | | | =商品名称(UTF-8) | | | | price= | | | | 价格(设置价*100) | | | | channelid=36 | | | | | | | | ( 33:第三方支 | | | | | | | | 付 | | | | | | | | 34:第三方支付 | | | | | | | | 35:第三方支付 | | | | | | | | 36: | | | | 第三方支付(默认) | | | | | | | | 37:第三方支付 | | | | | | | | 38:第三方支付 | | | | | | | | 39:第三方支付 | | | | | | | | ) | | | | | | | | rand | | | | str=随机的字符串 | | | | | | | | timest | | | | amp=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 端） | | +-------------+--------------------+----------------------------------+ | htt | | {"orderid":"原值返回 | | p://weburlC | ver=v1(接口版本号) | | | | | ","torderid | | | orderid =订单号 | ":"123","code":"0","msg":"消息"} | | | | | | | tord | | | | erid=订单号(第三方 | | | | ID) | | | | machid=机器设备 | | | | ID 号 | | | | | | | | channelid=渠道 | | | | id | | | | | | | | ra | | | | ndstr=随机的字符串 | | | | | | | | time | | | | stamp=201803271343 | | | | sign=认证签名 | | +-------------+--------------------+----------------------------------+ | | | code :0 | | | | 表示失败，失败时需要返回 msg | | | | | | | | code :1 消费者付款成功 | | | | | | | | code :2 正在等待消费者付款 | | | | | | | | code :3 表示此次交易已过期 | | | | | | | | code :4 表示此次交易已关闭 | | | | | | | | code :5 表示此次交易已完成 | +-------------+--------------------+----------------------------------+ | sign | | | | 认证 | | | | 请参考下面 | | | | 章节的 | | | | 鉴权方法 | | | +-------------+--------------------+----------------------------------+ | 交易 | | | | 有效时间由 | | | | 第三方设置 | | | | ,请求方在没 | | | | 有消费者主 | | | | 动退出付款 | | | | 界面的情况 | | | | 下,可以设置 | | | | 1-5 | | | | 分钟 | | | | 的等待时间 | | | +-------------+--------------------+----------------------------------+ 4.3 出货成功或失败通知接口 +--------------+-----------------------+-------------------------------+ | 请求网址 | 传递参数（A 端----> | 返回值 | | | C 端） | | +--------------+-----------------------+-------------------------------+ | ht | ver=v1(接口版本号) | {"orderid ":"原值返回 | | tp://weburlB | | | | | orderid | ","torderid":"123" | | | =订单号（小于 60 | ,"code":"0","msg":"消息内容"} | | | 位） | | | | t | | | | orderid=订单号(第三方 | | | | ID) | | | | | | | | machid=机器设备 ID | | | | 号trackno=轨道编号 | | | | | | | | status=0 或 1 | | | | | | | | (0 出货失败 1 | | | | 出货成功) | | | | er | | | | rinfo=错误信息(UTF-8) | | | | | | | | randstr=随机的字符串 | | | | | | | | t | | | | imestamp=201803271343 | | | | sign=认证签名 | | +--------------+-----------------------+-------------------------------+ | | | code:( 0 | | | | 表示失败,失败时需要返回 msg | | | | 1 表示成功处理) | +--------------+-----------------------+-------------------------------+ | sign | | | | 认证请参考 | | | | 下面 | | | | 章节的 | | | | 鉴权方法 | | | +--------------+-----------------------+-------------------------------+ 5.鉴权方法 为了防止接口被恶意调用，服务器需要对向接口传输的数据进行校验，具体方法如下： 1、每台机器，都会被分配一个 id（称为 machid）和一个密钥（appkey），密钥为一个字符串，由 16 个大小写字母或数字组成，不同机器的 machid 和密钥不一样，可以出厂前 define在代码中或是写在配置文件中。 2、调用任何接口时都要额外传输以下三个参数： randstr：随机的字符串，同样由 16 个大小写字母或数字组成，每次调用接口都应该重新生成。 timestamp：机器本地 Unix 时间戳，与全球标准时间的误差不要超过 2 分钟。 sign：签名，生成方法如下： 下面是一个示例，以机器请求产生订单为例，POST 的参数为： appkey 1234567890abcdef (默认值) randstr ok76oc1jkh2sy85o timestamp 20190105144625 sign 81fd6a8d97e3b775828028371a0cc85d6678d39a 先将 appkey 、timestamp 、randstr 三个参数进行字典序排序，得到字符串 1234567890abcdef 20190105144625 ok76oc1jkh2sy85o 然 后 对 这 个 字 符 串 进 行 sha1 加 密 ， 得 到 最 终 签 名81fd6a8d97e3b775828028371a0cc85d6678d39a 6.业务流程 开始 用户点击商品 进入支付界面， 获取二维码(4.1 接口) 用户支付， 售货机查询支付结果 （4.2 接口） 是 支付成功？ 开始出货 是出货成功？ 出上报出货结果 (4.3 接口) (建议退款) 结束