CloudPay.profitSharingReturn()

分账回退

说明

应用场景

  • 仅对订单进行退款时,如果订单已经分账,可以先调用此接口将指定的金额从分账接收方(仅限商户类型的分账接收方)回退给特约商户,然后再退款。
  • 回退以原分账请求为依据,可以对分给分账接收方的金额进行多次回退,只要满足累计回退不超过该请求中分给接收方的金额。
  • 此接口采用同步处理模式,即在接收到商户请求后,会实时返回处理结果。
  • 此功能需要接收方在商户平台-交易中心-分账-分账接收设置下,开启同意分账回退后,才能使用。 接口说明*

此接口与微信支付原分账接口(文档)的不同点在于:

  • 私有安全链路,免证书管理
  • 商户号填入 sub_mch_id 字段,小程序/公众号 appid 填入 sub_appid 字段
  • 免填写以下字段:mch_id、appid、sign、sign_type
  • 接口入参和返回值都为 JSON 而不是 XML

参数说明

名称 变量名 必填 类型 示例值 描述
子商户号 sub_mch_id string(32) 1900000109 微信支付分配的子商户号
子商户公众账号ID sub_appid string(32) wx8888888888888888 微信分配的子商户公众账号ID
随机字符串 nonce_str string(32) 5K8264ILTKCH16CQ2502SI8ZNMTM67VS 随机字符串,不长于32位。推荐随机数生成算法
微信分账单号 order_id 二选一 string(64) 3008450740201411110007820472 原发起分账请求时,微信返回的微信分账单号,与商户分账单号一一对应。
微信分账单号与商户分账单号二选一填写
商户分账单号 out_order_no string(64) P20180806125346 原发起分账请求时使用的商户后台系统的分账单号。
微信分账单号与商户分账单号二选一填写
商户回退单号 out_return_no string(64) R20190516001 此回退单号是商户在自己后台生成的一个新的回退单号,在商户后台唯一
只能是数字、大小写字母_-|*@ ,同一回退单号多次请求等同一次。
回退方类型 return_account_type string(32) MERCHANT_ID 枚举值:
MERCHANT_ID:商户ID
暂时只支持从商户接收方回退分账金额
回退方账号 return_account string(64) 86693852 回退方类型是MERCHANT_ID时,填写商户ID
只能对原分账请求中成功分给商户接收方进行回退
回退金额 return_amount int 888 需要从分账接收方回退的金额,单位为分,只能为整数,不能超过原始分账单分出给该接收方的金额
回退描述 description string(80) 用户退款 分账回退的原因描述

返回值说明

名称 变量名 必填 类型 示例值 描述
返回状态码 return_code string(32) SUCCESS 枚举值:
SUCCESS:分账回退处理成功
FAIL:分账回退处理失败
错误代码 error_code string(32) SYSTEMERROR 如果返回状态码为FAIL,则本字段存在,且为失败的错误码
详见错误码列表
返回信息 error_msg string(256) 参数格式校验错误 如果返回状态码为FAIL,则本字段存在,且为失败的错误信息

以下字段在return_code为SUCCESS的时候有返回

名称 变量名 必填 类型 示例值 描述
商户号 mch_id string(32) 1900000100 调用接口时提供的商户号
子商户号 sub_mch_id string(32) 1900000109 微信支付分配特约商户的商户号
公众账号ID appid string(32) wx8888888888888888 调用接口提供的公众账号ID
随机字符串 nonce_str string(32) 5K8264ILTKCH16CQ2502SI8ZNMTM67VS 微信返回的随机字符串
签名 sign string(64) C380BEC2BFD727A4B6845133519F3AD6 微信返回的签名,详见签名算法
微信分账单号 order_id string(32) 3008450740201411110007820472 原发起分账请求时,微信返回的微信分账单号
商户分账单号 out_order_no string(64) P20150806125346 原发起分账请求时使用的商户系统内部的分账单号。
商户回退单号 out_return_no string(64) R20150806125346 调用接口提供的商户系统内部的回退单号
微信回退单号 return_no string(64) 3008450740201411110007820472 微信分账回退单号,微信系统返回的唯一标识
回退方类型 return_account_type 枚举。string(32) MERCHANT_ID 枚举值:
MERCHANT_ID:商户ID
回退方账号 return_account string(64) 86693852 回退方类型是MERCHANT_ID时,商户ID
回退金额 return_amount int 888 回退金额,整数,单位为分
回退描述 description string(80) 用户退款 分账回退的原因描述
回退结果 result string(32) SUCCESS 枚举值:
PROCESSING:处理中
SUCCESS:已成功
FAILED: 已失败如果返回为处理中,请勿变更商户回退单号,使用相同的参数再次发起分账回退,否则会出现资金风险
在处理中状态的回退单如果5天没有成功,会因为超时被设置为已失败。
失败原因 fail_reason string(32) ACCOUNT_ABNORMAL 枚举值:
ACCOUNT_ABNORMAL:分账接收方账户异常
TIME_OUT_CLOSED: 超时关单
此字段仅回退结果为FAILED时存在
完成时间 finish_time string(16) 20180608170132 分账回退完成时间

错误码

名称 描述 原因 解决方案
SYSTEMERROR 接口返回错误 系统超时 请不要更换商户分账单号,请使用相同参数再次调用API。否则可能造成资金损失
NOTENOUGH 回退方账户余额不足 回退方账户余额不足,请先充值再回退 请不要更换商户分账单号,等待充值完毕后,请使用相同参数再次调用API。否则可能造成资金损失
NOAUTH 回退方不允许回退 回退方不允许分账回退 请先让回退方打开分账允许设置
ORDERNOTEXIST 分账指令不存在 分账指令不存在 分账指令不存在,请检查是否有相应的分账单
PARAM_ERROR 参数不正确,请检查参数 请求参数未按指引进行填写 return_account与mch_id不能填写为相同的商户号,不能自己给自己回退
INVALID_REQUEST 请求不合法 参数中APPID或 MCHID不存在等 请检查请求参数
FREQUENCY_LIMITED 频率限制 请求过多被频率限制 该笔请求未处理,请降低频率后原单重试,请勿更换商户回退单号
AMOUNT_OVERDUE 可退余额不足 回退金额大于剩余可从接收方回退的金额 请检查请求参数