[关闭]
@ulodev 2018-07-05T01:37:51.000000Z 字数 18283 阅读 1932

云支支付接口文档-公众号支付

云支

1. 引言

1.1. 阅读对象

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

1.2. 业务术语

1、刷卡支付
     请找商务索取最新文档。
2、扫码支付
     请找商务索取最新文档。
3、公众号支付
     公众号支付是用户在微信中打开商户的H5页面，商户在 H5页面通过调用微信支付提供的 JSAPI 接口调起微信支付模块完成支付。应用场景有：
     ◆用户在微信公众账号内进入商家公众号，打开某个主页面，完成支付
     ◆用户的好友在朋友圈、聊天窗口等分享商家页面链接，用户点击链接打开商家页面，完成支付
     ◆将商户页面转换成二维码，用户扫描二维码后在微信浏览器中打开页面后完成支付
4、APP 支付
     请找商务索取最新文档。
5、支付宝支付
     请找商务索取最新文档。
6、QQ 钱包支付
     请找商务索取最新文档。
7、百度钱包支付
     请找商务索取最新文档。

1.3. 支付账户

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

参数 API 参数名 详细说明
商户号 mch_id 商户申请云支服务后，由服务平台分配的商户收款账号。
API 密钥 key 交易过程生成签名的密钥，不会在网络中传播。商户妥善保管该 Key， 切勿在网络中传输，不能在其他客户端中存储，保证 key 不会泄露

1.3.2. 测试商户账户

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

参数 API 参数名 详细说明
商户号 50100011 商户申请云支服务后，由服务平台分配的商户收款账号。
API 密钥 8dd884b52409ad0a3d11013075bf3072 交易过程生成签名的密钥，不会在网络中传播。
金额 100 单位为分,1 元

2. 公众号支付

2.1. 场景介绍

商户已有 H5 商城网站，用户通过消息或扫描二维码在微信内打开网页时，可以调用微信支付完成下单购买的流程。

步骤（1）：如图 7.1，商户下发图文消息或者通过自定义菜单吸引用户点击进入商户网页。
步骤（2）：如图 7.2，进入商户网页，用户选择购买，完成选购流程。
1.png-42.4kB 2.png-45.6kB
图 7.1 商户自定义消息界面 图 7.2 商户网页下单

步骤（3）：如图 7.3，调起微信支付控件，用户开始输入支付密码。
步骤（4）：如图 7.4，密码验证通过，支付成功。商户后台得到支付成功的通知。
1.png-42.4kB 2.png-45.6kB
图 7.3 用户确认支付，输入密码 图 7.4 用户支付成功提示

步骤（5）：如图 7.5，返回商户页面，显示购买成功。该页面由商户自定义。
步骤（6）：如图 7.6，公众号下发消息，提示发货成功。该步骤可选。
1.png-42.4kB 2.png-45.6kB
图 7.5 返回商户页面提示 图 7.6 用户收到发货微信通知

注意：商户也可以把商品网页的链接生成二维码，用户扫一扫打开后即可完成购买支付

以下是支付场景的交互细节，请认真阅读，设计商户页面的逻辑：

（1）用户打开商户网页选购商品，发起支付，在网页通过JavaScript调用getBrandWCPayRequest接口，发起 微信支付请求，用户进入支付流程。
（2）用户成功支付点击完成按钮后，商户的前端会收到JavaScript的返回值。商户可直接跳转到支付成功的 静态页面进行展示。
（3）商户后台收到来自微信开放平台的支付成功回调通知，标志该笔订单支付成功。

注：（2）和（3）的触发不保证遵循严格的时序。JSAPI返回值作为触发商户网页跳转的标志，但商户后台应该只在收到微信后台的支付成功回调通知后，才做真正的支付成功的处理。

2.2. 业务流程

商户系统和微信支付系统主要交互：
1. 商户 server 调用统一下单接口请求订单，api 参见公共 api【统一下单 API】
2. 商户 server 接收支付通知，api 参见公共 api【支付结果通知 API】
3. 商户 server 查询支付结果，api 参见公共 api【查询订单 API】

3. 接口规则

3.1. 协议规则

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

传输方式 为保证交易安全性，采用HTTPS传输
提交方式 采用POST方法提交
数据格式 提交和返回数据都为XML格式，根节点名为xml
字符编码 统一采用UTF-8字符编码
签名算法 MD5，后续会兼容SHA1、SHA256、HMAC等
签名要求 请求和接收数据均需要校验签名，详细方法请参考[安全规范-签名算法]
证书要求 调用申请退款、撤销订单接口需要商户证书
判断逻辑为保证交易安全性，采用HTTPS传输

3.2. 参数规定

3.3. 安全规范

  1. appid： wxd930ea5d5a258f4f
  2. mch_id： 10000100
  3. device_info： 1000 body

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

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

第二步：拼接API 密钥：

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

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

  1. <xml>
  2. <appid>wxd930ea5d5a258f4f</appid>
  3. <mch_id>10000100</mch_id>
  4. <device_info>1000<device_info>
  5. <body>test</body>
  6. <nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
  7. <sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign>
  8. <xml>

3.4. 数据格式

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

  1. <xml>
  2. <return_code><![CDATA[FAIL]]></return_code>
  3. <return_msg><![CDATA[404 Not Found]]></return_msg>
  4. </xml>

正确返回数据：

  1. <xml>
  2. <bank_type><![CDATA[SPDB_CREDIT]]></bank_type>
  3. <fee_type><![CDATA[CNY]]></fee_type>
  4. <is_subscribe><![CDATA[Y]]></is_subscribe>
  5. <mch_id><![CDATA[15121009]]></mch_id>
  6. <openid><![CDATA[ozaUDwqSo51HvC0lw9CrL20KXlsQ]]></openid>
  7. <out_trade_no><![CDATA[20150303398]]></out_trade_no>
  8. <result_code><![CDATA[SUCCESS]]></result_code>
  9. <return_code><![CDATA[SUCCESS]]></return_code>
  10. <third_trans_id><![CDATA[1004970044201510081126012906]]></third_trans_id>
  11. <time_end><![CDATA[20151008112037]]></time_end>
  12. <total_fee><![CDATA[1]]></total_fee>
  13. <trade_state><![CDATA[SUCCESS]]></trade_state>
  14. <trade_type><![CDATA[trade.weixin.micropay]]></trade_type>
  15. <transaction_id><![CDATA[1512100920150925000000010]]></transaction_id>
  16. </xml>

业务级错误返回：

  1. <xml>
  2. <err_code><![CDATA[AUTHCODEEXPIRE]]></err_code>
  3. <err_code_des><![CDATA[请扫描微信支付被扫条码/二维码]]></err_code_des>
  4. <result_code><![CDATA[FAIL]]></result_code>
  5. <return_code><![CDATA[SUCCESS]]></return_code>
  6. </xml>

4. API 列表

4.1. 统一支付接口

4.1.1. 应用场景

除被扫支付场景以外，商户系统先调用该接口在微信支付服务后台生成预支付交易单，返回正确的预支付交易会话标识后再按扫码、JSAPI、APP等不同场景生成交易串调起支付。

4.1.2. 接口地址

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

4.1.3. 输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 nonce_str String(32) 否 随机字符串，不长于32位
商品描述 body String(32) 是 商品或支付单简要描述
商品详情 detail String(8192) 否 详见如下说明
附加数据 attach String(127) 否 详见如下说明
商户订单号 out_trade_no String(32) 是 商户系统内部的订单号,32 个字符内、可包含字母,其他说明见商户订单号
总金额 total_fee Int 是 订单总金额，单位为分，只能为整数，详见 支付金额
货币类型 fee_type String(16) 否 默认人民币：CNY，其他值列表详见 货币类型
终端 IP spbill_create_ip String(16) 是 调用微信支付API的机器IP
商品标记 goods_tag String(32) 否 商品标记，代金券或立减优惠功能的参数
通知地址 notify_url String(256) 是 接收支付结果异步通知回调地址，PC 网站必填，POS 机器扫码支付填写空字符串即可。示例：http://www.baidu.com/
通知地址 notify_url String(256) 是 接收支付结果异步通知回调地址，PC网站必填，POS机器扫码支付填写空字符串即可。示例：http://www.baidu.com/
交易类型 trade_type String(32) 是 取值：trade.weixin.jspay，详细说明见参数规定
操作终端类型 op_term_tp String(8) 否 取值：POS，WEB，PC
操作终端编号 op_term_no String(32) 否 终端设备号
操作门店编号 op_shop_no String(32) 否 门店编号
操作员编号 op_user_id String(32) 否 操作员帐号
签名 sign String(32) 是 签名，详见 签名生成算法

4.1.4. 返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断
返回信息 return_msg String(128) 否 返回信息，如非空，为错误原因:签名失败、参数格式校验错误
当return_code为SUCCESS的时候，还会包括以下字段：
返回状态码 return_code String(16) 是 SUCCESS/FAIL
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当return_code和result_code都为SUCCESS的时，还会包括以下字段：
商户号 mch_id String(32) 是 商户号
签名 sign String(32) 是 微信返回的签名，详见签名 签名生成算法
预支付 URL prepay_url String(255) 是 在微信内访问此 URL 地址，进行付款
预支付标识 prepay_id String(64) 是 预支付会话标识，用于后续接口调用中使用，该值有效期为2小时
交易类型 trade_type String(32) 是 取值：trade.weixin.jspay，详细说明见参数规定

4.1.5. 错误码

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

名称 描述 原因 解决方案
NOAUTH 商户无此接口权限 商户未开通此接口权限 请商户前往申请此接口权限
NOTENOUGH 余额不足 用户帐号余额不足 用户帐号余额不足，请用户充值或更换支付卡后再支付
ORDERPAID 商户订单已支付 商户订单已支付，无需重复操作 商户订单已支付，无需更多操作
ORDERCLOSED 订单已关闭 当前订单已关闭，无法支付 当前订单已关闭，请重新下单
SYSTEMERROR 系统错误 系统超时 系统异常，请用相同参数重新调用
APPID_NOT_EXIST APPID 不存在 参数中缺少 APPID 请检查 APPID 是否正确
MCHID_NOT_EXIST MCHID 不存在 参数中缺少 MCHID 请检查 MCHID 是否正确
APPID_MCHID_NOT_ MATCH appid 和 mch_id 不匹配 appid 和 mch_id 不匹配 请确认 appid 和 mch_id 是否匹配
LACK_PARAMS 缺少参数 缺少必要的请求参数 请检查参数是否齐全
OUT_TRADE_NO_USE D 商户订单号重复 同一笔交易不能多次提交 请核实商户订单号是否重复提交
SIGNERROR 签名错误 参数签名结果不正确 请检查签名参数和方法是否都符合签名算 法要求
XML_FORMAT_ERROR XML 格式错误 XML 格式错误 请检查 XML 参数格式是否正确
REQUIRE_POST_METH OD 请使用 post 方法 未使用 post 传递参数 请检查请求参数是否通过 post 方法提交
POST_DATA_EMPTY post 数据为空 post 数据不能为空 请检查 post 数据是否为空
NOT_UTF8 编码格式错误 未使用指定编码格式 请使用 NOT_UTF8 编码格式

4.2. 前端页面回调

4.2.1. 应用场景

    支付完成后，微信公众账号页面会引导用户跳转至商户提交订单所填的 return_url 上；但是该不跳转不会 携带支付成功相关的信息，商户需要自行调用查询订单接口进行交易结果查询判断。

4.3 支付结果通知

4.3.1. 应用场景

支付完成后，微信会把相关支付结果和用户信息发送给商户，商户需要接收处理，并返回应答。对后台通知交互时，如果微信收到商户的应答不是成功或超时，微信认为通知失败，微信会通过一定的策略（如30分钟共8次）定期重新发起通知 ， 尽可能提高通知的成功率，但微信不保证通知最终能成功。（通知频率为15/15/30/180/1800/1800/1800/1800/3600，单位：秒）

注意：同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行幵发控制，以避免函数重入造成的数据混乱。

特别提醒：商户系统对于支付结果通知的内容一定要做签名验证，防止数据泄漏导致出现“假通知”，造成资金损失。
◆ POS 机器需要主动调用 POS 前置查询接口，查询支付最终结果。POS 机无法得到后台通知结果。

4.3.2. 通知参数

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL，此字段是通信标识，非交易标识，交易是否成功需要查看result_code 来判断
返回信息 return_msg String(128) 否 返回信息，如非空，为错误原因（签名失败、参数格式校验错误等）
以下字段在return_code为SUCCESS的时候有返回
业务结果 result_code String(16) 是 SUCCESS/FAIL
返回状态码 return_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
以下字段在return_code和result_code都为SUCCESS的时候有返回
商户号 mch_id String(16) 是 调用接口提交的商户号
随机字符串 nonce_str String(16) 是 微信返回的随机字符串
用户标识 openid String(128) 是 用户在商户appid下的唯一标识
微信appid appid String(32) 是 公众号标识
是否关注公众账号 is_subscribe String(1) 否 用户是否关注公众账号，Y-关注，N-未关注，仅在公众账号类型支付有效
用户子标识 sub_openid String(128) 否 用户在子商户 appid 下的唯一标识
是否关注子公众账号 sub_is_subscribe String(1) 否 用户是否关注子公众账号，Y-关注，N-未关注，仅在公众账号类型支付有效
交易类型 trade_type String(16) 是 调用接口提交的交易类型，取值详细说明见参数规定
付款银行 bank_type String(16) 是 银行类型，采用字符串类型的银行标识
总金额 total_fee Int 是 订单总金额，单位为分
货币种类 fee_type String(8) 否 货币类型，符合 ISO 4217 标准的三位字母代码，默认人民币：CNY，其他值列表详见 货币类型
现金支付金额 cash_fee Int 是 现金支付金额订单现金支付金额，详见 支付金额
现金支付货币类型 cash_fee_type String(16) 否 货币类型，符合 ISO 4217 标准的三位字母代码，默 认人民币：CNY，其他值列表详见 货币类型
代金券或立减优惠金额 coupon_fee Int 否 “代金券或立减优惠”金额<=订单总金额，订单总金额-“代金券或立减优惠”金额=现金支付金额，详见 代金券或立减优惠
代金券或立减优惠使用数量 coupon_count Int 否 代金券或立减优惠使用数量
代金券或立减优惠批次 ID coupon_batch_id_$n String(20) 否 代金券或立减优惠批次ID,$n为下标，从0开始编号
代金券或立减 coupon_id_$n String(20) 否 代金券或立减优惠ID,$n为下标，从0开始编号
优惠 ID
单个代金券或立减优惠支付金额 coupon_fee_$n Int 否 单个代金券或立减优惠支付金额, $n 为下标，从 0 开始编号
平台支付订单号 transaction_id String(32) 是 平台支付订单号
微信支付订单号 third_trans_id String(32) 是 微信支付订单号
商户订单号 out_trade_no String(32) 是 商户系统的订单号，与请求一致。
附加数据 attach String(128) 否 附加数据，原样返回
支付完成时间 time_end String(14) 是 订单支付时间，格式为 yyyyMMddHHmmss，如 2009 年 12 月 25 日 9 点 10 分 10 秒表示为20091225091010。其他详见时间规则/td>

4.3.3. 返回参数

商户处理后同步返回给服务平台，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：

返回结果 结果说明
success 处理成功，服务平台系统收到此结果后不再进行后续通知
fail 或其它字符 处理不成功，服务平台系统收到此结果或者没有收到任何结果，系统通过补单机制再次通知


示例如下：

success

4.4. 查询订单接口

4.4.1. 应用场景

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

4.4.2. 接口地址

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

4.4.3. 请求参数

字段名 变量名 类型 必填 描述
平台订单号 transaction_ id String(32) 二选 一 平台订单号
商户订单号 out_trade_no String(32) 商户系统内部的订单号，当没提供 transaction_id 时需要传这个。
随机字符串 nonce_str String(32) 是 随机字符串，不长于 32 位。推荐 随机数生成算法
操作终端类型 op_term_tp String(8) 否 取值：POS，WEB，PC
操作终端编号 op_term_no String(32) 否 终端设备号
操作门店编号 op_shop_no String(32) 否 门店编号
操作员编号 op_user_id String(32) 否 操作员帐号
签名 sign String(32) 是 签名，详见 签名生成算法

4.4.4. 返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL此字段是通信标识，非交易标识，交易是否成功需要查看result_code 来判断
返回信息 return_msg String(128) 否 返回信息，如非空，为错误原因（签名失败、参数格式校验错误等）
以下字段在return_code为SUCCESS的时候有返回
业务结果 result_code String(16) 是 SUCCESS/FAIL
返回状态码 return_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
以下字段在return_code 和 result 都为SUCCESS的时候有返回
商户号 mch_id String(32) 是 商户号
用户标识 openid String(128) 是 用户在商户 appid 下的唯一标识
是否关注公众账号 is_subscribe String(1) 否 用户是否关注公众账号，Y-关注，N-未关注，仅在公众账号类型支付有效
用户子标识 sub_openid String(128) 否 用户在子商户 appid 下的唯一标识
是否关注子公众账号 sub_is_subscribe String(1) 否 用户是否关注子公众账号，Y-关注，N-未关注，仅在公众账号类型支付有效
交易类型 trade_type String(16) 是 调用接口提交的交易类型，取值详细说明见参数规定
交易状态 trade_state String(32) 是 SUCCESS—支付成功
REFUND—转入退款
NOTPAY—未支付
CLOSED—已关闭
REVOKED—已撤销（刷卡支付）
USERPAYING--用户支付中
PAYERROR--支付失败(其他原因，如银行返回失败)
付款银行 bank_type String(16) 是 银行类型，采用字符串类型的银行标识
总金额 total_fee Int 是 订单总金额，单位为分
货币种类 fee_type String(8) 否 货币类型，符合ISO 4217标准的三位字母代码，默认人民币：CNY，其他值列表详见 货币类型
现金支付金额 cash_fee Int 是 现金支付金额订单现金支付金额，详见 支付金额
现金支付货币类型 cash_fee_type String(16) 否 货币类型，符合 ISO 4217 标准的三位字母代码，默认人民币：CNY，其他值列表详见 货币类型
代金券或立减 优惠金额 coupon_fee Int 否 “代金券或立减优惠”金额<=订单总金额， 订单总金额-“代金券或立减优惠”金额=现金支付金额，详见 代金券或立减优惠
代金券或立减优惠使用数量 coupon_count Int 否 代金券或立减优惠使用数量
代金券或立减优惠批次 ID coupon_batch_i d_$n String(20) 否 代金券或立减优惠批次 ID ,$n 为下标，从 0 开始编号
代金券或立减优惠 ID coupon_id_$n String(20) 否 代金券或立减优惠 ID, $n 为下标，从 0 开始编号
单个代金券或立减优惠支付金额 coupon_fee_$n Int 否 单个代金券或立减优惠支付金额, $n 为下标，从 0 开 始编号
平台支付订单号 transaction_id String(32) 是 平台支付订单号
微信支付订单 号 third_trans_id String(32) 是 微信支付订单号
商户订单号 out_trade_no String(32) 是 商户系统的订单号，与请求一致。
附加数据 attach String(128) 否 附加数据，原样返回
支付完成时间 time_end String(14) 是 订单支付时间，格式为 yyyyMMddHHmmss，如 2009 年 12 月 25 日 9 点 10 分 10 秒表示为20091225091010。其他详见时间规则
交易状态描述 trade_state_des c String(256) 否 对当前查询订单状态的描述和下一步操作的指引

4.4.5. 错误码

名称 描述 原因 解决方案
ORDERNOTEXIST 此交易订单号不存在 查询系统中不存在此交易订单号 该 API 只能查提交支付交易返回成功的订单，请商户检查需要查询的订单号是否正确
SYSTEMERROR 系统错误 后台系统返回错误 系统异常，请再调用发起查询

4.5. 申请退款接口

4.5.1. 应用场景

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

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

4.5.2. 接口地址

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

4.5.3. 输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 nonce_str String(32) 是 随机字符串，不长于 32 位。推荐 随机数生成算法
平台订单号 transaction_id String(28) 二选一 平台生成的订单号，在支付通知中有返回
商户订单号 out_trade_no String(32) 商户的订单号
商户退款单号 out_refund_no String(32) 是 商户系统内部的退款单号，商户系统内部唯一，同一退款单号多次请求只退一笔
总金额 total_fee Int 是 订单总金额，单位为分，只能为整数，详见 支付金额
退款金额 refund_fee Int 是 退款总金额，订单总金额，单位为分，只能为整数，详见 支付金额
货币种类 refund_fee_type String(8) 否 货币类型，符合 ISO 4217 标准的三位字母代码，默认人民币：CNY，其他值列表详见 货币类型
操作终端类型 op_term_tp String(8) 否 取值：POS，WEB，PC
操作终端编号 op_term_no String(32) 否 终端设备号
操作门店编号 op_shop_no String(32) 否 门店编号
操作员编号 op_user_id String(32) 否 操作员帐号
签名 sign String(32) 是 签名，详见 签名生成算法

4.5.4. 返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断
返回信息 return_msg String(128) 否 返回信息，如非空，为错误原因（签名失败、参数格式校验错误等）
以下字段在return_code为SUCCESS的时候有返回
业务结果 result_code String(16) 是 SUCCESS/FAIL
返回状态码 return_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当 return_code和result_code 都为SUCCESS的时，还会包括以下字段：
商户号 mch_id String(32) 是 商户号
平台订单号 transaction_id String(28) 是 平台订单号
微信订单号 third_trans_id String(28) 是 微信订单号
商户订单号 out_trade_no String(32) 是 商户系统内部的订单号
商户退款单号 out_refund_no String(32) 是 商户退款单号
平台退款单号 refund_id String(28) 是 平台退款单号
微信退款单号 third_refund_id String(28) 是 微信退款单号
退款渠道 refund_channel String(16) 否 ORIGINAL—原路退款 BALANCE—退回到余额
退款金额 refund_fee Int 是 退款总金额,单位为分,可以做部分退款
订单总金额 total_fee Int 是 订单总金额，单位为分，只能为整数，详见 支付金额
订单金额货币种类 fee_type String(8) 否 订单金额货币类型，符合 ISO4217标准的三位字母代码，默认人民币：CNY，其他值列表详见 货币类型
现金支付金额 cash_fee Int 否 现金支付金额，单位为分，只能为整数，详见 支付金额
现金退款金额 cash_refund_fee Int 否 现金退款金额，单位为分，只能为整数，详见 支付金额
代金券或立减优惠退款金额 coupon_refund_f ee Int 否 代金券或立减优惠退款金额=订单金额-现金退款金额，注 意：立减优惠金额不会退回
代金券或立减优惠使用数量 coupon_refund_ count Int 否 代金券或立减优惠使用数量
代金券或立减优惠 ID coupon_refund_id String(20) 否 代金券或立减优惠 ID

4.5.5. 错误码

名称 描述 原因 解决方案
SYSTEMERROR 接口返回错误 系统超时 请用相同参数再次调用 API
INVALID_TRANSACTI ONID 无效 transaction_id 请求参数未按指引进 行填写 请求参数错误，检查原交易号是否存在或发起支付 交易接口返回失败
PARAM_ERROR 参数错误 请求参数未按指引进行填写 请重新检查再调用退款申请
APPID_NOT_EXIST APPID 不存在 参数中缺少 APPID 请检查 APPID 是否正确
MCHID_NOT_EXIST MCHID 不存在 参数中缺少 MCHID 请检查 MCHID 是否正确
APPID_MCHID_NOT_MATCH appid 和 mch_id 不匹配 appid 和 mch_id 不匹配 请确认 appid 和 mch_id 是否匹配
REQUIRE_POST_METH OD 请使用 post 方法 未使用 post 传递参 数 请检查请求参数是否通过 post 方法提交
SIGNERROR 签名错误 参数签名结果不正确 请检查签名参数和方法是否都符合签名算法要求
XML_FORMAT_ERROR XML 格式错误 XML 格式错误 请检查 XML 参数格式是否正确

4.6. 查询退款接口

应用场景

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

4.6.1. 接口地址

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

4.6.2. 输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 nonce_str String(32) 是 随机字符串，不长于 32 位。推荐 随机数生成算法
签名 sign String(32) 是 签名，详见 签名生成算法
操作终端类型 op_term_tp String(8) 否 取值：POS，WEB，PC
操作终端编号 op_term_no String(32) 否 终端设备号
操作门店编号 op_shop_no String(32) 否 门店编号
操作员编号 op_user_id String(32) 否 操作员帐号
平台订单号 transaction_id String(28) 四 选 一 平台订单号
商户订单号 out_trade_no String(32) 商户系统内部的订单号
商户退款单号 out_refund_no String(32) 商户退款单号
平台退款单号 refund_id String(28) 微信生成的退款单号，在申请退款接口有返回

4.6.3. 返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断
返回信息 return_msg String(128) 否 返回信息，如非空，为错误原因（签名失败、参数格式校验错误等）
以下字段在 return_code 为 SUCCESS 的时候有返回
业务结果 result_code String(16) 是 SUCCESS/FAIL
返回状态码 return_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当return_code和 result_code 都为 SUCCESS 的时，还会包括以下字段：
商户号 mch_id String(32) 是 商户号
平台订单号 transaction_id String(32) 是 平台订单号
微信订单号 third_trans_id String(32) 是 微信订单号
商户订单号 out_trade_no String(32) 是 商户系统内部的订单号
订单总金额 total_fee Int 是 订单总金额，单位为分，只能为整数，详见 支付金额
订单金额货币种类 fee_type String(8) 否 订单金额货币类型，符合 ISO 4217 标准的三位字母代码，默认人民币：CNY，其他值列表详见 货币类型
现金支付金额 cash_fee Int 是 现金支付金额，单位为分，只能为整数，详见 支付金额
退款笔数 refund_count Int 是 退款记录数
商户退款单号 out_refund_no_$n String(32) 是 商户退款单号
平台退款单号 refund_id_$n String(28) 是 平台退款单号
退款渠道 refund_channel_$n String(16) 否 ORIGINAL—原路退款 BALANCE—退回到余额
退款金额 refund_fee_$n Int 是 退款总金额,单位为分,可以做部分退款
代金券或立减优惠退款金额 coupon_refund_fee_$n Int 否 代金券或立减优惠退款金额<=退款金额，退款金额-代金券或立减优惠退款金额为现金，说明详见 代金券或立减优惠
代金券或立减优惠使用数量 coupon_refund_count_$n Int 否 代金券或立减优惠使用数量 ,$n 为下标,从 0 开始编号
代金券或立减优惠批次 ID coupon_refund_batch_id_$n_$m String(20) 否 批次 ID ,$n 为下标，$m 为下标，从 0 开始编号
代金券或立减优惠 ID coupon_refund_id_$n_$m String(20) 否 代金券或立减优惠 ID, $n 为下标，$m 为下标，从 0 开 始编号
单个代金券或立减优惠支付金额 coupon_refund_fee_$n_$m Int 否 单个代金券或立减优惠支付金额, $n 为下标，$m 为下标， 从 0 开始编号
退款状态 refund_status_$n String(16) 是 退款状态：SUCCESS—退款成功
FAIL—退款失败
PROCESSING—退款处理中
NOTSURE—未确定，需要商户原退款单号重新发起
CHANGE—转入代发，退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，资金回流到商户的现金帐号，需要商户人工干预，通过线下或者财付通转账的方式进 行退款。

4.6.4. 错误码

名称 描述 原因 解决方案
SYSTEMERROR 接口返回错误 系统超时 请尝试再次掉调用 API。
INVALID_TRANSACTIONID 无效transaction_ id 请求参数未按指引进行填写 请求参数错误，检查原交易号是否存在或发起支付交易接口返回失败
PARAM_ERROR 参数错误 请求参数未按指引进行填写 请检查参数再调用退款申请
APPID_NOT_EXIST APPID 不存在 参数中缺少 APPID 请检查 APPID 是否正确
MCHID_NOT_EXIST MCHID 不存在 参数中缺少 MCHID 请检查 MCHID 是否正确
APPID_MCHID_NOT_MATCH appid 和 mch_id 不匹配 appid 和 mch_id 不匹配 请确认 appid 和 mch_id 是否匹配
REQUIRE_POST_METHOD 请使用 post 方法 未使用 post 传递参数 请检查请求参数是否通过 post 方法提交
SIGNERROR 签名错误 参数签名结果不正确 请检查签名参数和方法是否都符合签名算法要求
XML_FORMAT_ERROR XML 格式错 XML 格式错误 请检查 XML 参数格式是否正确

4.7. 下载账单接口

4.7.1. 应用场景

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

4.7.2. 接口地址

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

4.7.3. 请求参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 nonce_str String(32) 是 随机字符串，不长于 32 位。推荐 随机数生成算法
对账单日期 bill_date String(8) 是 下载对账单的日期，格式：20140603
签名 sign String(32) 是 签名，详见 签名生成算法

4.7.4. 返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 FAIL（失败）,成功时，数据以文本表格的方式返回 result_code 来判断
返回信息 return_msg String(128) 否 返回信息，如非空，为错误原因（签名失败、参数格式校验错误等）

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

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

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

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

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

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

4.7.5. 错误码

名称 描述 原因 解决方案
SYSTEMERROR 系统错误 后台系统返回错误
添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注