云支服务接口文档-刷卡支付

云支

1. 引言

1.1. 阅读对象

本文阅读对象：商户系统（在线购物平台、人工收银系统、自动化智能收银系统或其他）集成微信、支付宝、QQ钱包支付涉及的技术架构师，研发工程师，测试工程师，系统运维工程师。

1.2. 业务术语

1、刷卡支付
     刷卡支付是用户展示微信钱包内的“刷卡条码/二维码”给商户系统扫描后直接完成支付的模式。主要应用线下面对面收银的场景。
2、扫码支付
     请找商务索取最新文档。
3、公众号支付
     请找商务索取最新文档。
4、H5支付
     请找商务索取最新文档。
5、APP 支付
     请找商务索取最新文档。
6、支付宝支付
     请找商务索取最新文档。
7、QQ 钱包支付
     请找商务索取最新文档。
8、百度钱包支付
     请找商务索取最新文档。

1.3. 支付账户

商户在云支服务平台(申请扫码支付、公众号支付)按照相应提示，申请相应支付模式。工作人员审核资料无误后开通相应的支付模式，如：微信支付、支付宝支付、百度钱包、QQ钱包支付等。申请审核通过后，商户在申请资料填写的邮箱中收取到由云支服务平台发送的邮件，此邮件包含开发时需要使用的支付账户信息

1.3.1. 服务账户参数说明

1.3.2. 测试商户账户

注意：此账户为生产环境商户账户，接口需调用生产环境接口地址！

2. 刷卡支付

2.1. 场景介绍

步骤 1：用户选择刷卡支付付款并打开微信，进入“我” ->“钱包” ->“刷卡”条码界面；
步骤 2：收银员在商户系统操作生成支付订单，用户确认支付金额；
步骤 3：商户收银员用扫码设备扫描用户的条码/二维码，商户收银系统提交支付；
步骤 4：微信支付后台系统收到支付请求，根据验证密码规则判断是否验证用户的支付密码，不需要验证密码的交易直接发起扣款，需要验证密码的交易会弹出密码输入框。支付成功后微信端会弹出成功页面，支付失败会弹出错误提示。

我的钱包	刷卡界面

输入密码，确认支付	支付成功后页面提示

2.2. 支付验证密码规则

• 支付金额>1000 元的交易需要验证用户支付密码
• 用户每天最多有 5 笔交易可以免密，超过后需要验证密码
• 微信支付后台判断用户支付行为有异常情况，符合免密规则的交易也会要求验证密码

2.3. 案例介绍

目前已上线刷卡支付案例，商户可自行前往店里实际体验。
便利店：711 便利店、国大 36524、好邻居等。
连锁药店：老百姓大药房、国大药房、海王星辰等。
超市：天虹等。
根据商户具体的情况，刷卡支付接入模式可分为：商户后台接入和门店接入。
根据用户是否需要输入支付密码可分为：免密模式和验密模式。

2.3.1. 接入模式-商户后台接入

该模式适合具备统一后台系统的商户。门店收银台与商户后台通信，商户后台系统负责与微信支付系统发送交易请求和接收返回结果。

商户后台接入刷卡支付流程图

2.3.2. 接入模式-门店接入

该模式适合门店收银台通过公网直接不微信后台通信的商户。 门店收银台直接发起交易请求和处理返回结果。
商户可以根据实际需要，处理门店和商户后台系统之间的其它业务流程

门店接入刷卡支付流程图

2.3.3. 免密支付流程

本节以商户后台接入模式说明支付流程，请参看以下时序图：

刷卡支付免密流程时序图

流程详细说明：
（1）收银员在商户收银台生成支付订单，向用户展示支付金额；
（2）用户打开微信客户端，点击“我的钱包”，选择“刷卡”，进入条码界面；
（3）使用扫码设备读取用户手机屏幕上的条码；
（4）扫码设备将读取的信息上传给门店收银台；
（5）门店收银台得到支付信息后，向商户收银后台发起支付请求；
（6）商户后台对门店收银台的支付请求进行处理，生成签名后调用【提交刷卡支付 API】向微信支付系统发起支付请求；
（7）微信支付系统得到商户侧的支付请求之后会对请求进行验证，验证通过之后会对请求数据进行处理，最后将处理后的支付结果返回给商户收银后台。如果支付成功，微信支付系统会将支付结果返回给商户，同时把支付结果通知给用户（以短信、微信消息的形式通知）；
（8）商户收银后台对得到的支付结果进行签名验证和处理，再将支付结果返回给门店收银台；
（9）收银员看到门店收银台的支付结果后给用户发账。

2.3.4. 验密支付流程

场景交互与免密模式相同，不同的是在商户调用【提交刷卡支付API】发起支付请求之后，微信支付后台提示用户输入密码确认支付，接口同步返回USERPAYING状态，商户系统再轮询调用查询订单接口来确认当前用户是否已经支付成功。

以下时序图说明验密支付流程：

刷卡支付验证密码流程时序图

由于在商户收银后台向微信支付系统发起支付请求之前的流程是完全一样的，所以这里只介绍商户发起支付请求之后的逻辑。
（1）商户门店生成订单后，收银台向后台系统发起支付请求；
（2）后台调用微信支付【提交刷卡支付 API】生成支付交易；
（3）微信支付系统对商户请求进行验证，验证通过后判断当前用户需要输入密码；
（4）微信支付系统返回 USERPAYING 状态，商户后台系统将应答结果返回给商户门店收银；
（5）微信支付系统通知用户微信客户端输入密码；
（6）用户得到输入密码提示后，确认支付并输入密码；
（7）完成密码输入，提交微信支付；
（8）微信客户端在用户完成支付后提示微信支付后台系统返回的支付结果，而且微信支付系统会通过短信、微信消息给用户发送支付结果提醒；
（9）商户收银台得到 USERPAYING 状态后，经过商户后台系统调用【查询订单 API】查询实际支付结果；
（10）如果支付结果仍为 USERPAYING，则每隔 5 秒循环调用【查询订单 API】判断实际支付结果，如果用户取消支付或累计30秒用户都未支付，商户收银台退出查询流程后继续调用【撤销订单 API】撤销支付交易。

2.3.5. 异常处理

用户遇到支付异常，请按如下说明处理
（1）用户微信端弹出系统错误提示框，用户可在交易列表查看交易情况，如果未找到订单，需要商户重新发起支付交易；如果订单显示成功支付，商户收银系统再次调用【查询订单 API】查询实际支付结果；
（2）用户微信端弹出支付失败提示，例如：余额不足，信用卡失效。需要重新发起支付；
（3）当交易超时或支付交易失败，商户收银系统必须调用【撤销订单 API】，撤销此交易；
（4）由于银行系统异常、用户余额不足、不支持用户卡种等原因使当前支付交易失败，商户收银系统应该把错误提示明确展示给收银员；
（5）根据返回的错误码，判断是否需要撤销交易，具体详见 API 返回错误码列表。

3. 接口规则

3.1. 协议规则

调用API 必须遵循以下规则:

3.2. 参数规定

• 交易金额
  交易金额默认为人民币交易，接口中参数支付金额单位为【分】，参数值不能带小数。对账单中的交易金额单位为【元】。外币交易的支付金额精确到币种的最小单位，参数值不能带小数点。

• 交易类型
  trade.weixin.jspay--微信公众号支付，调用统一下单接口
  trade.weixin.native--微信扫码支付，调用统一下单接口
  trade.weixin.apppay--微信APP支付，调用统一下单接口
  trade.weixin.h5pay--微信h5支付，调用统一下单接口
  trade.weixin.micropay--微信刷卡支付，刷卡支付有单独的支付接口，不调用统一下单接口
  trade.alipay.native--支付宝扫码支付，调用统一下单接口
  trade.alipay.jspay--支付宝公众号支付，调用统一下单接口
  trade.alipay.micropay–-支付宝小额支付，刷卡支付有单独的支付接口，不调用统一下单接口

• 货币类型
  货币类型的取值列表：
  CNY：人民币

• 时间
  标准北京时间，时区为东八区；如果商户的系统时间为非标准北京时间，参数值必须根据商户系统所在时区先换算成标准北京时间，例如商户所在地为0时区的伦敦，当地时间为2014年11月11日0时0分0秒，换算成北京时间为：2014年11月11日8时0分0秒

• 时间戳
  标准北京时间，时区为东八区，自1970年1月1日0点0分0秒以来的秒数。注意：部分系统取到的值为毫秒级，需要转换成秒(10位数字)。

• 商户订单号
  商户支付的订单号由商户自定义生成，要求商户订单号保持唯一性（建议根据当前系统时间加随机序列来生成订单号）。重新发起一笔支付要使用原订单号，避免重复支付；已支付过或已调用关单、撤销（请见后文的API列表）的订单号不能重新发起支付。

3.3. 安全规范

• 签名算法
  签名生成的通用步骤如下：
  第一步，设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即 key1=value1&key2=value2…）拼接成字符串stringA。

  特别注意以下重要规则：
  ◆ 参数名 ASCII 码从小到大排序（字典序）；
  ◆ 如果参数的值为空不参与签名；也就是说参数是空的不需要参与签名；
  ◆ 参数名区分大小写；
  ◆ 验证调用返回或主动通知签名时，传送的 sign 参数不参与签名，将生成的签名与该sign值作校验；
  ◆ 支付接口可能增加字段，验证签名时必须支持增加的扩展字段；
  
  

• 生成随机数算法
  支付API 接口协议中包含字段nonce_str，主要保证签名不可预测。我们推荐生成随机数算法如下：调用随机数函数生成，将得到的值转换为字符串。
  例： 假设传送的参数如下

appid： wxd930ea5d5a258f4f
mch_id： 10000100
device_info： 1000 body

第一步：对参数按照key=value的格式，按照参数名ASCII 字典序排序如下：

stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100
&nonce_str=ibuaiVcKdpRxkhJA";

第二步：拼接API 密钥：

stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"

最终得到最终发送的数据：

<xml>
<appid>wxd930ea5d5a258f4f</appid>
<mch_id>10000100</mch_id>
<device_info>1000<device_info>
<body>test</body>
<nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
<sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign>
<xml>

3.4. 数据格式

采用标准XML协议，所有参数只存在一级节点中，不采用多级节点嵌套。
协议级错误返回：

<xml>
<return_code><![CDATA[FAIL]]></return_code>
<return_msg><![CDATA[404 Not Found]]></return_msg>
</xml>

正确返回数据：

<xml>
<bank_type><![CDATA[SPDB_CREDIT]]></bank_type>
<fee_type><![CDATA[CNY]]></fee_type>
<is_subscribe><![CDATA[Y]]></is_subscribe>
<mch_id><![CDATA[15121009]]></mch_id>
<openid><![CDATA[ozaUDwqSo51HvC0lw9CrL20KXlsQ]]></openid>
<out_trade_no><![CDATA[20150303398]]></out_trade_no>
<result_code><![CDATA[SUCCESS]]></result_code>
<return_code><![CDATA[SUCCESS]]></return_code>
<third_trans_id><![CDATA[1004970044201510081126012906]]></third_trans_id>
<time_end><![CDATA[20151008112037]]></time_end>
<total_fee><![CDATA[1]]></total_fee>
<trade_state><![CDATA[SUCCESS]]></trade_state>
<trade_type><![CDATA[trade.weixin.micropay]]></trade_type>
<transaction_id><![CDATA[1512100920150925000000010]]></transaction_id>
</xml>

业务级错误返回：

<xml>
<err_code><![CDATA[AUTHCODEEXPIRE]]></err_code>
<err_code_des><![CDATA[请扫描微信支付被扫条码/二维码]]></err_code_des>
<result_code><![CDATA[FAIL]]></result_code>
<return_code><![CDATA[SUCCESS]]></return_code>
</xml>

4. API 列表

4.1. 刷卡支付接口

4.1.1. 应用场景

收银员使用扫码设备读取微信用户刷卡授权码以后，二维码或条码信息传送至商户收银台，由商户收银台或者商户后台调用该接口发起支付。
提醒 1：提交支付请求后微信会同步返回支付结果。当返回结果为“系统错误”时，商户系统等待 5 秒后调用【查询订单API】，查询支付实际交易结果；当返回结果为“USERPAYING”时，商户系统可设置间隔时间(建议10秒)重新查询支付结果，直到支付成功或超时(建议30秒)。
提醒 2：在调用查询接口返回后，如果交易状况不明晰，请调用【撤销订单 API】，此时如果交易失败则关闭订单，该单不能再支付成功；如果交易成功，则将扣款退回到用户败户。当撤销无返回或错误时，请再次调用。
注意：请勿扣款后立即调用【撤销订单 API】 ,建议至少 5 分钟后再调用。

注：该支付接口统一整合了支付宝、微信的小额刷卡支付，后台动态区分该笔交易是支付宝付款还是微信付款，前端调用无需判断，如支付类型未开通的，需要联系商务进行开通

4.1.2. 接口地址

生产环境地址：https://api.yunzhikj.cn/pay/micropay

4.1.3. 输入参数

4.1.4. 返回结果

4.1.5. 错误码

注意：如果当前交易返回的支付状态是明确的错误原因造成的支付失败（支付确认失败），请重新下单支付；如果当前交易返回的支付状态是不明错误（支付结果未知），请调用查询订单接口确认状态。

4.2. 查询订单接口

4.2.1. 应用场景

该接口提供所有支付订单的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。 需要调用查询接口的情况：
◆ 当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；
◆ 调用支付接口后，返回系统错误或未知交易状态情况；
◆ 调用被扫支付 API，返回 USERPAYING 的状态；
◆ 调用关单或撤销接口API 之前，需确认支付状态。

4.2.2. 接口地址

生产环境地址：https://api.yunzhikj.cn/pay/orderquery

4.2.3. 请求参数

4.2.4. 返回结果

4.2.5. 错误码

4.4. 申请退款接口

4.4.1. 应用场景

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，支付将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。

注意：退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。 一笔退款失败后重新提交，要采用原来的退款单号。总退款金额不能超过用户实际支付金额。

4.4.2. 接口地址

生产环境地址：https://api.yunzhikj.cn/secapi/pay/refund

4.4.3. 输入参数

4.4.4. 返回结果

4.4.5. 错误码

4.5. 查询退款接口

4.5.1. 应用场景

提交退款申请后，通过调用该接口查询退款状态。退款有一定延时，用零钱支付的退款20分钟内到账，银行卡支付的退款 3 个工作日后重新查询退款状态。

4.5.2. 接口地址

生产环境地址：https://api.yunzhikj.cn/pay/refundquery

4.5.3. 输入参数

4.5.4. 返回结果

4.5.5. 错误码

4.6. 下载账单接口

4.6.1. 应用场景

商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和平台侧数据不一致，通过对账单核对后可校正支付状态。
注意：
1、平台侧未成功下单的交易不会出现在对账单中。
2、平台在次日 10 点启动生成前一天的对账单，建议商户 11 点后再获取。
3、对账单中涉及金额的字段单位为“元”。
4、对账单接口只能下载三个月以内的账单。

4.6.2. 接口地址

生产环境地址：https://api.yunzhikj.cn/pay/downloadbill

4.6.3. 请求参数

4.6.4. 返回结果

成功时，数据以文本表格的方式返回，第一行为表头，后面各行为对应的字段内容，字段内容跟查询订单或退款结果一致，具体字段说明可查阅相应接口。

第一行为表头：
交易时间,商户号,子商户号,设备号,平台单号,第三方单号,商户单号,用户标识,交易类型,交易状态,付款银行,货币 种类,总金额,红包金额,平台退款单号,商户退款单号,退款金额,企业红包退款金额,退款类型,退款状态,商品 名称, 商户数据包

从第二行起，为数据记录，各参数以逗号分隔，参数前增加`符号，为标准键盘 1 左边键的字符，字段顺序表头不一致。

倒数第二行为订单统计标题，最后一行为统计数据总交易单数，总交易额，总退款金额，总红包退款金额
示例如下：

交易时间,商户号,子商户号,设备号,平台单号,第三方单号,商户单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金 额,红包金额,平台退款单号,商户退款单号,退款金额,企业红包退款金额,退款类型,退款状态,商品名称,商户数据包

`2016-09-03     10:40:11,`15121009,`15121009,`,`1512100920160903109790993,`8012016090310243946534287,`201609031039491
05714,`,`trade.weixin.jspay,`SUCCESS,`,`CNY,`0.01,`0,`,`,`0,`0,`,`,`测试购物,`
`2016-09-03     14:56:38,`15121009,`15121009,`,`1512100920160903149824853,`8012016090314245624846302,`201609031456288
62401,`,`trade.weixin.jspay,`SUCCESS,`,`CNY,`0.01,`0,`,`,`0,`0,`,`,`测试购物,`
总交易单数,总交易额,总退款金额,总红包退款金额
`2,`0.02,`0.00,`0

4.6.5. 错误码