机具对接流程

最近更新时间:2019-12-02 10:51:58

对接流程

HTTPS API 说明请参见 HTTPS API

注意:

其中请求方的 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.com
    sz.pay.qcloud.com
    sh.pay.qcloud.com
    tj.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 字段,每个品牌机具取值区间需在云支付分配,请勿随意填写或不填。

目录