机具对接流程

最近更新时间:2019-01-22 20:58:26

1. 对接流程

HTTPS API 说明请参见 HTTPS API

注意:

其中请求方的 HTTPS 握手协议需是 TLS1.1 及以上的协议,否则链接会不通。

服务商/子商户入驻总流程请参见 配置文档

1.1 HTTPS API 交易流程

刷卡支付接入流程(顾客被扫)

说明:

  • 刷卡支付接口:https://pay.qcloud.com/cpay/micro_pay
  • 查询订单接口:https://pay.qcloud.com/cpay/query_order
  • 支付结果未知包含:网络请求超时和业务上的结果未知,详情请参见 HTTPS API 对 status 的说明。
  • 接口返回 status 为0,只表示业务请求成功,订单的支付结果需要通过订单的状态来判断。
  • 如果2分钟内查询不到结果,请到手机端管理系统查看交易明细确认支付结果。

退款接入流程

说明:

  • 申请退款成功,并不代表退款成功。
    退款是一个异步过程,申请退款成功后,只是代表第三方支付平台受理这笔退款,是否到账需要看这笔钱退到哪里。
    • 如果是退款至微信零钱账户或支付宝账户,会很快到账。
    • 如果是退款至顾客的银行卡,到账时间与银行处理进度相关,可能要花几个小时。
      因此申请退款成功后,需告知顾客,申请退款已经成功,请关注后续到账情况。顾客可以关注微信或支付宝的消息,便能收到已经发起退款或退款到账的消息。
  • 如果想在设备上看这笔退款是否到账,可以调用退款查询接口,通过退款单的状态来查看是否退款成功。适配者可以自己选择是否适配退款查询接口。

2. 机具配置

2.1 获取配置二维码

管理员登录手机商户管理系统,找到需要配置的设备,进行下图设置:

注意:

  • 添加设备时,需选择移动收款机具,之后请求选择店员再继续操作,如果没有店员,需先创建店员再生成配置二维码。
  • 生成的二维码链接如下:https://pay.qcloud.com/cpay/use_device_setting?osi=xxxx&si=xxxx,其中二维码的有效期是5分钟。
  • 只有商户管理员能够获取配置二维码。

2.2 机具绑定/解绑流程

说明:

  • 扫码配置二维码后,请求后台的 url 需要增加 sn 号,获取配置的请求为 http get 请求。
  • 配置二维码,有效期是5分钟。
  • 机具绑定和解绑需要有语音提示。
  • 机具需要支持重复配置,在配置异常时,就可以重新开始配置。

2.3 绑定配置接口说明

2.3.1 绑定配置 url

GET https://pay.qcloud.com/cpay/use_device_setting?osi=xxxx&si=xxxx&sn=xxxxx

注意:

请求是 get 请求,不是 post 请求。

2.3.2 请求参数

参数 含义 类型 长度 是否必填 备注
osi 全局门店 ID String 20字节 必填 配置二维码中的参数osi
si 云支付生成的配置 ID String 20字节 必填 配置二维码中的参数si
sn sn 号 String 64字节 必填 sn 号为:厂家名称简称_型号_厂家 sn 号,其中厂家名称简称和型号都要求英文大写字母,保证不同厂家之间 sn 号唯一,以联迪为例 qm500 就是 LANDI_QM500_1923840238029389

2.3.3 响应参数

响应为一个 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 号。

2.4 解绑配置接口说明

2.4.1 解绑配置 url

接口

https://pay.qcloud.com/cpay/unbind_device_sn_code

方法

POST 方法,content_type 为 application/json

2.4.2 请求参数

参数 含义 类型 长度 是否必填 备注
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 号

2.4.3 响应参数

响应为一个 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 已经解绑了之前绑定的设备。

2.5 交易接口说明

  • 在使用支付、退款、查询订单和查询退款单四个接口时,需要在请求的 OrderClient 结构里增加一个 sn_code 字段(类型 string),表示绑定设备的 sn 号,否则交易流程会走不通。
  • 退款使用认证密钥计算认证码即可。

3. 验收标准

3.1 必需功能

  1. 支持配置
    • 统一在云支付手机端管理系统配置。
    • 支持绑定和解绑流程。
    • 支持重新绑定;例如第一种情况:机具先绑定了之后商户的认证密钥更新了就需要重新绑定机具;第二种情况:手机端管理系统设备被删除了,机具也需要重新绑定其他设备。
  2. 支持连接方式
    支持直连云支付。
  3. 支持刷卡支付
    • 需要输入密码,显示“等待用户输入密码中”。
    • 支付结果未知,显示“通过订单查询确认支付结果或手机端商户管理系统确认支付结果”。
  4. 支持订单退款
    收银员扫订单条码,再查询订单得到订单总金额,会显示一个订单总金额作为默认的退款金额,如果需要部分退款,收银员修改金额即可。
  5. 支持订单查询
    云支付商户有2种订单号前缀,一种是带字符的10位,例如:sz0100lmnx;一种是纯数字的8位,例如:01000052,建议使用纯数字的8位前缀,便于机具扫描订单条码时容易扫上。
  6. 支持店员可设置
  7. 支持机具可升级
    • 优先在线升级。
    • 其他升级方式。
  8. 支持多域名
    机具需要支持多个域名切换,使用 /cpay/ping 接口可以探测域名是否能用。
    云支付一共有如下4个域名:
    pay.qcloud.com
    sz.pay.qcloud.com
    sh.pay.qcloud.com
    tj.pay.qcloud.com
    第一种探测方式: 例如列出4个域名,选择第一个,如果第一个不行,自动探测第二个,如果第二个不行,自动探测第三个,知道选择结果是否 OK,给出相应的提示语。
    第二种探测方式:支付的时候自动切换。
  9. 支持扫码配置 WIFI
  10. 支持 OrderClient 增加 sub terminal type 字段
    云支付分配。
  11. 支持打印小票
  12. 支持语音播报
  13. 机具操作手册
    厂商提供服务商使用机具的操作手册。

3.2 可选功能

机具没有提供以下3个功能时,收银员可在手机端商户管理系统查看配置。

  1. 交易流水
  2. 汇总统计
  3. 语音区分支付平台

4. 测试用例和注意事项

4.1 刷卡支付

以下采用微信支付0.02,支付宝支付0.02测试,建议用户使用其他金额再次进行测试。

  • 测试用户输入密码的情形(正常情况下,账号当日支付超过10笔开始要求输入密码)。

需注意的边界情况:

  1. 不能语音播报超时但用户支付成功。
  2. 支付金额0(包括输入0.001等四舍五入后为0的)应在机具层面拦截下,提示用户。

4.2 退款和查单

以下流程对微信支付、支付宝分别进行测试:

  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,请注意机具的处理能力,防止宕机。

4.3 语音播报

支付和退款都能正确播报平台和金额,应注意播报用户需要的结果信息,而不仅是播报“成功”或“查询成功”。

4.4 其他

必须正确填写 sub_terminal_type 字段,每个品牌机具取值区间需在云支付分配,请勿随意填写或不填。