订单退款接口

有时因为卖家或买家的原因需要进行退款操作，统一平台支持同一个订单，可分多次退款（总次数小于等于10次），单次退款金额须大于0元，小于等于订单总金额，所有批次总退款的金额不能超过该订单总金额；退款允许的最大时间间隔由客户端系统在平台注册后进行设置，默认为30天，即从付款起算，超过该时间将无法退款，注意设置不能超过平台设定的最大退款时间限制（平台限制取决于支付渠道和营运方设置）。

客户端系统采用POST方式向平台接口发起退款请求，当同一个订单下有多笔退款时，请按时间先后分批进行，避免由于并发问题导致的退款失败（平台采用并发锁机制，确保同一时刻同一订单仅接受一个退款申请），接口地址如下：

https://平台域名/yunke-order/refund  
如：https://pay.wn.com/yunke-order/refund

退款请求：

请求参数如下：

订单退款POST请求参数
参数名 类型 是否必选 限制 描述 示例
user_id int 是 系统分配，不可自定义 用户id：商家在平台注册时获得的用户ID 4
order_number string 是

长度:string[6,32]
仅限大小写字母、数字、下划线

 商户订单号：在商家系统中全局唯一 20210530_R060524
refund_number string 按条件

长度:string[6,32]
仅限大小写字母、数字、下划线

 退款单号：用以唯一标识同一个订单中的一个退款申请，退款失败重新提交时，请不要更换退款单号，务必使用原退款单号；当省略该参数时，表示一次性全额退款 R060524_1
amount float 是 可带小数点精确到分，值大于0，小于等于订单总金额 退款金额：单位：元 18.6
reason string 可选 string[1, 80] 退款原因：若传入，会在下发给用户的退款消息中体现退款原因 示例值：商品已售完
notify_url string 可选 string[1, 256]必须为直接可访问的URL绝对地址，且异步通知地址不能重定向 退款异步通知地址：部分支付渠道退款有一个过程，不能立即处理，此URL绝对地址用于异步通知商家退款是否成功，如无将不通知，采用POST方法通知，参数见下 https://www.drupal.org
sign string 是 长度string[64]
哈希值

签名字符串：用于保证请求真实、不被篡改、防止重放攻击，通讯必须签名，点击查看签名算法

  

 

接口响应如下：
响应分为公共参数部分和业务参数部分

公共参数部分
参数名 类型 是否必选 限制 描述 示例
code int 是 三位整数 处理结果的状态码，详见这里 2000
msg string 是 长度string[1,256] 处理结果的描述短语 “ok”
sign string 是 长度string[64]
哈希值

签名字符串：用于保证请求真实、不被篡改、防止重放攻击，通讯必须签名，点击查看签名算法

  
业务参数部分（当code状态码指示业务正常时，以下参数才存在）
参数名 类型 是否必选 限制 描述 示例
user_id int 是 系统分配 用户id：商家在平台注册时获得的用户ID 4
order_number string 是 长度:string[6,32]
仅限大小写字母、数字、下划线		 商户订单号：在商家系统中全局唯一 20210530_R060524
system_number string 是 目前暂定长度:24位数字
前12位表示时间，8位随机数，4位产品类别		 在统一平台中的系统订单号，全局唯一
将来可能会升位，用户应预留32位储存		 210602150849375331066319
refund_number string 按条件

长度:string[6,32]
仅限大小写字母、数字、下划线

 退款单号：用以唯一标识同一个订单中的一个退款申请，退款失败重新提交时，请不要更换退款单号，务必使用原退款单号；当省略该参数时，表示一次性全额退款 R060524_1
amount float 是 可带小数点精确到分，值大于0，小于等于订单总金额 退款金额：单位：元 18.6
total float 是 可带小数点精确到分
取值范围为 0.01~100000000.00		 订单总付款金额：单位元 18.6
reason string 可选 string[1, 80] 退款原因：若传入，会在下发给用户的退款消息中体现退款原因 示例值：商品已售完
notify_url string 可选 string[1, 256]必须为直接可访问的URL绝对地址，且异步通知地址不能重定向 退款异步通知地址：用于通知商家退款是否成功的异步通知URL绝对地址，如无将不通知，采用POST方法通知，参数见下 https://www.drupal.org
success_time int 按条件 Unix时间戳（ 1970年1月1日 00:00:00 到当前时间的秒数） 成功退款的时间，如不成功则不存在 1622341093
refund_state int 是 一位整数 退款状态：0表示退款等待中，1退款成功，2退款失败 这是关键参数，如失败可再次尝试
refund_time int 是 Unix时间戳（ 1970年1月1日 00:00:00 到当前时间的秒数） 退款申请发起的时间 1622341093

退款异步通知：
部分第三方支付渠道的退款请求有一个过程，不能马上处理，因此只有当处理完成时才能采用异步通知的方式通知退款状态，比如微信支付即是如此，但支付宝会立即处理，为了统一起见，平台也会进行异步通知，异步通知的参数与退款请求的响应参数完全相同，因此当退款请求的响应结果显示退款在等待中时，请留意异步通知，如果退款请求中没有一并传递异步通知地址那么不会进行异步通知，此时你也可以采用退款查询接口发起主动查询（详见退款查询接口）
注意：如果你传递了异步通知地址，那么平台就会发起异步通知，而不论支付渠道是否能够立即处理退款，像支付宝这样立即处理退款的渠道，平台发给客户端系统的异步通知通常在退款请求响应之前就会收到。

注意：
1、当退款请求响应或异步通知签名验证失败时，必须放弃处理，避免冒用攻击，当签名验证通过，客户端系统应依据退款情况，做相应业务处理（业务处理也可在退款异步通知中进行，或通过其他机制触发执行，如任务队列等）
2、如果退款失败，可采用原退款单号发起重试，当采用同一个退款单号多次发起退款申请时，涉及的金额等数据以第一次申请为准
3、退款查询请求发起时间建议不要和退款请求时间间隔太短，建议10秒以上
4、异步通知可能会发起多次，客户端系统应判断退款状态做业务处理