[关闭]
@ulodev 2018-06-20T10:24:20.000000Z 字数 17146 阅读 1526

云支支付接口文档-app支付小程序

云支

1. 引言

1.1. 阅读对象

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

1.2. 业务术语

1、刷卡支付
     请找商务索取最新文档。
2、扫码支付
     请找商务索取最新文档。
3、app支付小程序
     app支付小程序是用户在商家APP内拉起微信支付
4、APP 支付
     请找商务索取最新文档。
5、支付宝支付
     请找商务索取最新文档。
6、QQ 钱包支付
     请找商务索取最新文档。
7、百度钱包支付
     请找商务索取最新文档。

1.3. 支付账户

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

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

1.3.2. 测试商户账户

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

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

2. app支付小程序

2.1. 场景介绍

商户已有APP，用户通过商户已有APP拉起微信支付，可以调用app支付小程序完成下单购买的流程。

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位
支付场景标识 show_type String(32) 是 固定值：“2”，用在APP拉起微信支付,详见4.2 APP 调起微信
商品描述 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/
交易类型 trade_type String(32) 是 取值：trade.weixin.jspay，详细说明见参数规定
指定支付方式 limit_pay String(32) 否 no_credit--指定不能使用信用卡支付
操作终端类型 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) 是 微信返回的签名，详见签名 签名生成算法
预支付数据包 package_json String(255) 是 该参数为 JSON 格式，参数配置微信JSAPI拉起微信支付
预支付标识 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. APP 调起微信

4.2.1. APP 端开发步骤说明

统一支付接口 packge_json 返回的字段说明，用于传递给SDK：
可参照提供的SDK Demo拉起微信支付

字段名 变量名 类型 必填 描述
应用 ID app_id String(32) 是 微信开放平台実核通过的应用 APPID
原始id orginal_id String(32) 是 原始id
预支付交易会话ID prepay_id String(32) 是 微信返回的支付交易会话 ID

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下的唯一标识
用户子标识 sub_openid String(128) 否 用户在子商户 appid 下的唯一标识
交易类型 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 下的唯一标识
用户子标识 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 系统错误 后台系统返回错误
添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注