对接流程
注意
其中请求方的 HTTPS 握手协议需是 TLS1.1 及以上的协议，否则连接会失败。
HTTPS API 交易流程
刷卡支付接入流程（顾客被扫）
?
刷卡支付接口：
https://pay.qcloud.com/cpay/micro_pay。查询订单接口：
https://pay.qcloud.com/cpay/query_order。支付结果未知包含：网络请求超时和业务上的结果未知，详情请参见 HTTPS API 对 status 的说明。
接口返回 status 为0，只表示业务请求成功，订单的支付结果需要通过订单的状态来判断。
如果2分钟内查询不到结果，请到手机端管理系统查看交易明细确认支付结果。
退款接入流程
?
申请退款成功，并不代表退款成功。
退款是一个异步过程，申请退款成功后，只是代表第三方支付平台受理这笔退款，是否到账需要看这笔钱退到哪里。
如果是退款至微信零钱账户或支付宝账户，会很快到账。
如果是退款至顾客的银行卡，到账时间与银行处理进度相关，可能要花几个小时。
因此申请退款成功后，需告知顾客，申请退款已经成功，请关注后续到账情况。顾客可以关注微信或支付宝的消息，便能收到已经发起退款或退款到账的消息。
如果想在设备上看这笔退款是否到账，可以调用退款查询接口，通过退款单的状态来查看是否退款成功。适配者可以自己选择是否适配退款查询接口。
机具配置
获取配置二维码
管理员登录手机商户管理系统，找到需要配置的设备，进行下图设置：
添加设备时，需选择移动收款机具>配置设备，完成后需选择店员，如果没有店员，需先创建店员再生成配置二维码。
生成的二维码链接如下：
https://pay.qcloud.com/cpay/use_device_setting?osi=xxxx&si=xxxx，二维码的有效期是5分钟。只有商户管理员能够获取配置二维码。
?
机具绑定/解绑流程
?
扫码配置二维码后，请求后台的 url 需要增加 sn 号，获取配置的请求为 HTTPS GET 请求。
配置二维码，有效期是5分钟。
机具绑定和解绑需要有语音提示。
机具需要支持重复配置，在配置异常时，就可以重新开始配置。
绑定配置接口说明
绑定配置 url
执行命令：
GET https://pay.qcloud.com/cpay/use_device_setting?osi=xxxx&si=xxxx&sn=xxxxx。注意
请求是 get 请求，不是 post 请求。
请求参数
参数 | 含义 | 类型 | 长度 | 是否必填 | 备注 |
osi | 全局门店 ID | String | 20字节 | 必填 | 配置二维码中的参数 osi |
si | 云支付生成的配置 ID | String | 20字节 | 必填 | 配置二维码中的参数 si |
sn | sn 号 | String | 64字节 | 必填 | sn 号为：厂家名称简称_型号_厂家 sn 号，其中厂家名称简称和型号都要求英文大写字母，保证不同厂家之间 sn 号唯一，以联迪为例 qm500 就是 LANDI_QM500_1923840238029389 |
响应参数
响应为一个 json 字符串，包含以下字段：
参数 | 类型 | 子参数 | 子参数类型 | 含义 | 长度 | 是否一定返回 | 备注 |
status | Number | - | - | 错误码 | - | 一定 | 参见 HTTPS API 说明 |
description | String | - | - | 错误描述 | 不超过128字节 | 一定 | - |
log_id | Number | - | - | 日志 ID，用于定位问题 | - | 一定 | 调用方无需关注 |
internal_status | Number | - | - | 详细错误码 | - | 一定 | 调用方无需关注 |
use_device_setting | json 结构 | - | - | - | - | 一定 | - |
- | - | out_mch_id | String | 云支付服务商号 | 20字节 | 一定 | - |
- | - | out_sub_mch_id | String | 云支付子商户号 | 20字节 | 一定 | - |
- | - | cloud_cashier_id | String | 云支付商户订单前缀 | 8字节 | 一定 | 8位纯数字 |
- | - | authen_type | Number | 认证类型 | - | 一定 | 参见 HTTPS API 说明 |
- | - | authen_key | String | 认证密钥 | 32字节 | 一定 | - |
- | - | out_shop_id | String | 全局门店 ID | 20字节 | 一定 | - |
- | - | shop_name | String | 门店名称 | 不超过128字节 | 一定 | - |
- | - | device_id | String | 设备 ID | 不超过64字节 | 一定 | - |
- | - | device_name | String | 设备名称 | 不超过128字节 | 一定 | - |
- | - | staff_id | String | 员工 ID | 不超过64字节 | 一定 | - |
- | - | staff_name | String | 员工名称 | 不超过128字节 | 一定 | - |
说明
如果 internal_status 等于3214，表示云支付的 device_id 已经绑定了其他 sn 号。
解绑配置接口说明
解绑配置 url
接口
https://pay.qcloud.com/cpay/unbind_device_sn_code方法
POST 方法，content_type 为 application/json。
请求参数
参数 | 含义 | 类型 | 长度 | 是否必填 | 备注 |
request_content | 请求内容 | RequestContent | - | 必填 | 详见本节 RequestContent；打包方式参见 HTTPS API 说明 |
authen_info | 认证信息 | AuthenInfo | - | 必填 | 参见 HTTPS API 说明 |
RequestContent 结构
参数 | 含义 | 类型 | 长度 | 是否必填 | 备注 |
out_sub_mch_id | 云支付分配给子商户的账号 | String | 20字节 | 必填 | - |
out_shop_id | 云支付唯一标识门店的账号 | String | 20字节 | 必填 | 手机端管理系统显示的云支付全局门店 ID |
device_id | 云支付门店内的设备 ID | String | 20字节 | 必填 | 手机端管理系统门店内的设备 ID |
sn_code | sn 号 | String | 64字节 | 必填 | 调用绑定接口时使用的 sn 号 |
响应参数
响应为一个 json 字符串，包含以下字段：
参数 | 含义 | 类型 | 长度 | 是否必填 | 备注 |
response_content | 响应内容 | ResponseContent | - | 必填 | 详见本节 ResponseContent；解析方式参见 HTTPS API 说明 |
authen_info | 认证信息 | AuthenInfo | - | 必填 | 参见 HTTPS API 说明 |
ResponseContent 结构
参数 | 含义 | 类型 | 长度 | 是否必填 | 备注 |
status | 错误码 | Number | - | 必填 | 参见 HTTPS API 说明 |
description | 错误描述 | String | 256 | 必填 | - |
log_id | 日志 ID | Number | - | 必填 | - |
internal_status | 具体错误码 | Number | 256 | 必填 | 厂商一般不需要关注具体错误码 |
说明
如果 internal_status 等于3215，表示云支付的 device_id 已经与原绑定设备解绑。
交易接口说明
在使用支付、退款、查询订单和查询退款单四个接口时，需要在请求的 OrderClient 结构里增加一个 sn_code 字段（类型 string），表示绑定设备的 sn 号，否则交易流程会走不通。
退款使用认证密钥计算认证码即可。
验收标准
必需功能
1. 支持配置
统一在云支付手机端管理系统配置。
支持绑定和解绑流程。
支持重新绑定；例如第一种情况：机具已绑定商户，在商户的认证密钥更新后需要重新绑定机具；第二种情况：手机端管理系统设备被删除后，机具需要重新绑定其他设备。
2. 支持连接方式
支持直连云支付。
3. 支持刷卡支付
需要输入密码，显示“等待用户输入密码中”。
支付结果未知，显示“通过订单查询确认支付结果或手机端商户管理系统确认支付结果”。
4. 支持订单退款
收银员扫订单条码，再查询订单得到订单总金额，会显示一个订单总金额作为默认的退款金额，如果需要部分退款，收银员修改金额即可。
5. 支持订单查询
云支付商户有2种订单号前缀，一种是带字符的10位，例如：sz0100lmnx；一种是纯数字的8位，例如：01000052，建议使用纯数字的8位前缀，便于机具扫描订单条码时容易扫上。
6. 支持店员可设置
7. 支持机具可升级
优先在线升级。
其他升级方式。
8. 支持多域名
机具需要支持多个域名切换，使用
/cpay/ping 接口可以探测域名是否能用。
云支付一共有如下4个域名：
pay.qcloud.comsz.pay.qcloud.comsh.pay.qcloud.comtj.pay.qcloud.com
第一种探测方式： 例如列出4个域名，选择第一个，如果第一个不行，自动探测第二个，如果第二个不行，自动探测第三个，知道选择结果是否能用，给出相应的提示语。
第二种探测方式：支付的时候自动切换。9. 支持扫码配置 WIFI
10. 支持 OrderClient 增加 sub terminal type 字段
云支付分配。
11. 支持打印小票
12. 支持语音播报
13. 机具操作手册
厂商提供服务商使用机具的操作手册。
可选功能
机具未提供以下3个功能时，收银员可在手机端商户管理系统查看配置。
1. 交易流水
2. 汇总统计
3. 语音区分支付平台
测试用例和注意事项
刷卡支付
以下采用微信支付0.02，支付宝支付0.02测试，建议用户使用其他金额再次进行测试。
测试用户输入密码的情形（正常情况下，账号当日支付超过10笔开始要求输入密码）。
需注意的边界情况：
1. 不能语音播报超时但用户支付成功。
2. 支付金额0（包括输入0.001等四舍五入后为0的）应在机具层面拦截，并提示用户。
退款和查单
以下流程对微信支付、支付宝分别进行测试：
1. 支付0.02，应支付成功。
2. 扫订单号条码，应显示支付成功。
3. 退款0.03，应在机具层拦截，并提示超过可退金额。
4. 继续退款0.01，应退款成功。
5. 扫订单号条码，应显示订单状态为已部分退款。
6. 继续退款0.02，应拦截并提示超过可退金额。
7. 继续退款0.01，应退款成功。
8. 扫订单号，订单状态应显示已全额退款。
注意
current_trade_state 字段只有全额退款时才会变为4，否则一直为2（成功），所以不能通过 query_order 接口判断支付宝订单是否发生过部分退款。
使用 client_order_detail 查订单得到订单的 refunded_fee 值，才能判断是否已经部分退款，但 client_order_detail 接口目前返回报文大小可能超过10k，请注意机具的处理能力，防止宕机。
语音播报
支付和退款都能正确播报平台和金额，应注意播报用户需要的结果信息，而不仅是播报“成功”或“查询成功”。
其他
必须正确填写 sub_terminal_type 字段，每个品牌机具取值区间需在云支付分配，请勿随意填写或不填。
