@ulodev 2018-05-30T07:04:30.000000Z 字数 16499 阅读 1385

云支服务接口文档-京东扫码支付

云支

云支服务接口文档-京东扫码支付

1. 引言

1.1. 阅读对象

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

1.2. 支付账户

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

1.2.1. 服务账户参数说明

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

1.2.2. 测试商户账户

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

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

2. 接口规则

2.1. 协议规则

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

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

2.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–-支付宝小额支付，刷卡支付有单独的支付接口，不调用统一下单接口
trade.qqpay.micropay--QQ钱包小额支付，刷卡支付有单独的支付接口，不调用统一下单接口
trade.qqpay.native--QQ钱包扫码支付，调用统一下单接口
trade.qqpay.jspay--QQ钱包公众号支付，调用统一下单接口
trade.qqpay.wappay--QQ钱包WAP支付，调用统一下单接口
trade.baidu.native--百度扫码支付，调用统一下单接口
trade.jdpay.native--京东线下扫码支付，调用统一下单接口
trade.jdpay.onlinepay--京东线上扫码支付，调用统一下单接口
trade.jdpay.h5pay--京东线上H5支付，调用统一下单接口
trade.jdpay.micropay--京东小额支付，刷卡支付有单独的支付接口，不调用统一下单接口
货币类型
货币类型的取值列表：
CNY：人民币
时间
标准北京时间，时区为东八区；如果商户的系统时间为非标准北京时间。参数值必须根据商户系统所在时区先换算成标准北京时间，例如商户所在地为0时区的伦敦，当地时间为2014年11月11日0时0分0秒，换算成北京时间为：2014年11月11日8时0分0秒
时间戳标准北京时间，时区为东八区，自 1970年1月1日0点0分0秒以来的秒数。注意：部分系统取到的值为毫秒级，需要转换成秒(10 位数字)。
商户订单号商户支付的订单号由商户自定义生成，要求商户订单号保持唯一性（建议根据当前系统时间加随机序列来生成订单号）。重新发起一笔支付要使用原订单号，避免重复支付；已支付过或已调用关单、撤销（请见后文的 API 列表）的订单号不能重新发起支付。

2.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>

2.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.jdpay.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>

3. API 列表

3.1. 统一支付接口

3.1.1. 应用场景

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

3.1.2. 接口地址

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

3.1.3. 输入参数

字段名	变量名	类型	必填	描述
商户号	mch_id	String(32)	是	商户号
随机字符串	nonce_str	String(32)	是	随机字符串，不长于32位
京东账号	user_id	String(64)	否	userid为商户平台的用户id（相当于token，用于唯一标示用户），需通过接口参数传给京东。首次支付成功后userid会和用户登陆的手机号做绑定，下次用户再发起支付时，无需再次登录即可完成支付。京东线上扫码为必传字段
商品描述	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
回调地址	return_url	String(16)	是	默认人民币：CNY
商品标记	goods_tag	String(32)	否	商品标记，代金券或立减优惠功能的参数
通知地址	notify_url	String(256)	是	接收支付结果异步通知回调地址，PC 网站必填，POS 机器扫码支付填写空字符串即可。示例：http://www.baidu.com/
交易类型	trade_type	String(32)	是	取值：trade.jdpay.onlinepay，详细说明见 3.2 参数规定
指定支付方式	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)	是	签名

3.1.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)	是	商户号
签名	sign	String(32)	是	返回的签名
交易类型	trade_type	String(32)	是	取值：trade.jdpay.onlinepay，详细说明见参数规定
预支付URL	prepay_url	String(255)	是	PC端浏览器访问该链接地址
预支付标识	prepay_id	String(64)	是	预支付会话标识，用于后续接口调用中使用

3.1.5. 错误码

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

名称	描述	原因	解决方案
NOAUTH	商户无此接口权限	商户未开通此接口权限	请商户前往申请此接口权限
NOTENOUGH	余额不足	用户帐号余额不足	用户帐号余额不足，请用户充值或更换支付卡后再支付
ORDERPAID	商户订单已支付	商户订单已支付，无需重复操作	商户订单已支付，无需更多操作
ORDERCLOSED	订单已关闭	当前订单已关闭，无法支付	当前订单已关闭，请重新下单
SYSTEMERROR	系统错误	系统超时	系统异常，请用相同参数重新调用
MCHID_NOT_EXIST	MCHID 不存在	参数中缺少 MCHID	请检查 MCHID 是否正确
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 编码格式

3.2. 支付结果通知

3.2.1. 应用场景

支付完成后，云支服务会把相关支付结果和用户信息发送给商户，商户需要接收处理，并返回应答。对后台通知交互时，如果收到商户的应答不是成功或超时，会认为通知失败，云支服务会通过一定的策略（如30分钟共8 次）定期重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功。（通知频率为15/15/30/180/1800/1800/1800/1800/3600，单位：秒）
注意：同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行幵发控制，以避免函数重入造成的数据混乱。
特别提醒：商户系统对于支付结果通知的内容一定要做签名验证，防止数据泄漏导致出现“假通知”，造成资金损失。
◆ POS 机器需要主动调用 POS 前置查询接口，查询支付最终结果。POS 机无法得到后台通知结果。

3.2.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)	是	返回的随机字符串
交易类型	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)	是	支付订单号/第三方单号
京东单号	bank_no	String(32)	否	京东单号
商户订单号	out_trade_no	String(32)	是	商户系统的订单号，不请求一致。
附加数据	attach	String(128)	否	附加数据，原样返回
支付完成时间	time_end	String(14)	是	订单支付时间，格式为 yyyyMMddHHmmss，如 2009 年 12 月 25 日 9 点 10 分 10秒表示为20091225091010。其他详见时间规则

3.2.3. 返回参数

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

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

示例如下：

success

3.3. 查询订单接口

3.3.1. 应用场景

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

3.3.2. 接口地址

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

3.3.3. 请求参数

字段名	变量名	类型	必填	描述
商户号	mch_id	String(32)	是	商户号
平台订单号	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)	是	签名

3.3.4. 返回结果

字段名	变量名	类型	必填	描述
返回状态码	return_code	String(16)	是	SUCCESS/FAIL此字段是通信标识，非交易标识，交易是否成功需要查看result_code 来判断
返回信息	return_msg	String(128)	否	返回信息，如非空，为错误原因签名失败参数格式校验错误
以下字段在return_code为SUCCESS的时候有返回
商户号	mch_id	String(32)	是	调用接口提交的商户号
随机字符串	nonce_str	String(32)	是	返回的随机字符串
签名	sign	String(32)	是	返回的签名
业务结果	result_code	String(16)	是	SUCCESS/FAIL
错误代码	err_code	String(32)	否	详细参见错误列表
错误代码描述	err_code_des	String(128)	否	错误返回的信息描述
以下字段在return_code 和 result 都为SUCCESS的时候有返回
商户号	mch_id	String(32)	是	商户号
交易类型	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，如 200 9 年 12 月 25 日 9 点 10 分 10 秒表示为 20091225091 010。其他详见时间规则
交易状态描述	trade_state_des c	String(256)	否	对当前查询订单状态的描述和下一步操作的指引

3.3.5. 错误码

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

3.4. 申请退款接口

3.4.1. 应用场景

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

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

3.4.2. 接口地址

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

3.4.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_typ e	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)	是	签名

3.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_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)	否	订单金额货币类型，符合 ISO 4217 标准的三位字母代码，默认人民币：CNY
现金支付金额	cash_fee	Int	否	现金支付金额，单位为分，只能为整数
现金退款金额	cash_refund_fee	Int	否	现金退款金额，单位为分，只能为整数
代金券或立减优惠退款金额	coupon_refund_f ee	Int	否	代金券或立减优惠退款金额=订单金额-现金退款金额，注意：立减优惠金额不会退回
代金券或立减优惠使用数量	coupon_refund_ count	Int	否	代金券或立减优惠使用数量
代金券或立减优惠 ID	coupon_refund_i d	String(20)	否	代金券或立减优惠 ID

3.4.5. 错误码

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

3.5. 查询退款接口

3.5.1. 应用场景

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

3.5.2. 接口地址

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

3.5.3. 输入参数

字段名	变量名	类型	必填	描述
商户号	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)		生成的退款单号，在申请退款接口有返回

3.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(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—转入代发，退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，资金回流到商户的现金帐号，需要商户人工干预，通过线下或者财付通转账的方式进行退款。

3.5.5. 错误码

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

3.6. 下载账单接口

3.6.1. 应用场景

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

3.6.2. 接口地址

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

3.6.3. 请求参数

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

3.6.4. 返回结果

字段名	变量名	类型	必填	描述
返回状态码	return_code	String(16)	是	SUCCESS/FAIL## 标题 ## 此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断
返回信息	return_msg	String(128)	否	返回信息，如非空，为错误原因签名失败参数格式校验错误

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

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

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

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

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

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

3.6.5. 错误码

名称	描述	原因	解决方案
SYSTEMERROR	系统错误	后台系统返回错误	系统异常，请再调用发起查询