分账回退排障:return_mchid 该填出资方,sub_mchid 才是收钱方
调分账回退最常见的三类事故,按出现频次排序:两个商户号填反、PROCESSING 状态换了 out_return_no 重发、把「先退款再回退」的顺序套到 APIv3 上。先把结论摆出来:
- 方向:
return_mchid填原分账的接收方(钱从这里出);回退接口里的sub_mchid是「分账回退的接收商户,对应原分账出资的分账方」——也就是钱回到的那一方。填反后资金会进入错误账户,或被直接拒绝。 - 前提:接收方类型必须是
MERCHANT_ID,分账单状态FINISHED,分账result=SUCCESS;分账给个人的不支持;接收方要开启「同意分账回退」,否则403 NO_AUTH。 - 状态机:
PROCESSING不是终态,禁止换out_return_no,必须用相同参数重发;同一回退单 5 天未成功会转FAILED(TIME_OUT_CLOSED)。 - 顺序:除 B2b 以外的三套接口族走「先回退、再退款」,B2b 小程序是「先完成退款、再回退」,顺序相反。
- 耦合:退款与分账回退无强耦合,二级商户余额充足时可以不回退,直接退款。
分账接口族之间(分账、完结分账、解冻)的互斥关系不在这里展开,站内 #8583 已经写过;本文只讨论回退这一侧。
一、两个商户号分别代表谁
普通商户/服务商 APIv3 的请求体里没有第二个商户号字段,方向问题只出现在 return_mchid:它对应请求分账时传入的 receiver_account,也就是原分账接收方账号。金额就是从这个账户扣回去。
平台收付通 APIv3 多一个 sub_mchid,也是最容易填反的地方。文档写得很直白:sub_mchid 是「分账回退的接收商户,对应原分账出资的分账方商户」。原分账里是收钱的一方,回退里就是出钱的一方;原分账里出钱的分账方,回退里变成收钱方。两个字段指向的账户正好相反。
V2 字段名不同,语义一致:return_account 填写商户号 mch_id 或 sub_mch_id,且「只能对原分账请求中成功分给商户接收方回退」,return_account_type 仅支持 MERCHANT_ID。
自己不能给自己回退。V2 在 return_account 与 mch_id 相同时返回 PARAM_ERROR;B2b 也明确「不支持回退给自己,分账回退出资商户不允许和接收商户相同」。
二、能发起回退的前提
四道过滤条件,缺一不可:
- 接收方类型为
MERCHANT_ID(商户号)。分账给个人的分账单不支持回退。 - 分账单状态
FINISHED(处理完成),且分账结果result=SUCCESS。 - 接收方已在商户平台-交易中心-分账-分账接收设置下开启「同意分账回退」,否则
403 NO_AUTH,报错文案是「回退方未开通分账回退功能」。平台收付通文档另有一句:商户类型的接收方自动开通了分账回退,可以直接调接口。遇到NO_AUTH时,先按实际接口族核对这条开关,不要只依据文档里那句「自动开通」。 - 时间窗 180 天。超过 6 个月的订单,请求时必须带
transaction_id。
金额约束上,累计回退总额不能超过原分账单分给该接收方的金额。超出返回 403 NOT_ENOUGH(V2 是 AMOUNT_OVERDUE)。V3 文档另写了一条限额:同一笔分账单最多发起 50 次回退请求——多次小额回退虽然金额不超,次数也会用完该限额。
out_return_no 是商户后台唯一的回退单号,同一单号多次请求等同一次请求。这是后面做幂等的基础。
三、状态机:PROCESSING 只能原单重发
result 只有三个取值:
| 取值 | 含义 | 处理动作 |
|---|---|---|
PROCESSING | 处理中,非终态 | 用相同参数、相同 out_return_no 重发,或走查询接口 |
SUCCESS | 已成功,终态 | 结束,落库 |
FAILED | 已失败,终态 | 换新 out_return_no 重试,记录 fail_reason |
PROCESSING 状态下变更商户回退单号会产生资金风险——同一笔回退在微信侧仍在处理,新单号会再发起一次。回退单在 PROCESSING 状态持续 5 天未成功,会被置为 FAILED,fail_reason 为 TIME_OUT_CLOSED。
FAILED 的 fail_reason 有五种:ACCOUNT_ABNORMAL(原分账接收方账户异常)、BALANCE_NOT_ENOUGH(余额不足)、TIME_OUT_CLOSED(超时关单)、PAYER_ACCOUNT_ABNORMAL(原分账分出方账户异常)、INVALID_REQUEST(描述参数设置失败)。
频率限制也会遇到:429 FREQUENCY_LIMITED。V2 文档给的处置是「请降低频率后原单重试,请勿更换商户回退单号」——限流不是失败,不构成换号理由。
四、三套接口族的前提差异
| 接口族 | 请求 | 方向字段 | 特有前提 |
|---|---|---|---|
| 普通商户 APIv3 | POST /v3/profitsharing/return-orders | return_mchid | 请求体无 sub_mchid |
| 服务商 APIv3 | 同上 | return_mchid | sub_mchid 为特约商户号;接收方需开启同意分账回退 |
| 平台收付通 APIv3 | POST /v3/ecommerce/profitsharing/returnorders | return_mchid + sub_mchid | sub_mchid 必填,指回退接收商户 |
| V2 | POST https://api.mch.weixin.qq.com/secapi/pay/profitsharingreturn | return_account | 双向证书 + HMAC-SHA256 签名,30QPS,同步处理 |
三类接口都只支持对「分给商户接收方」的分账单回退,都限 180 天,都是同步返回处理结果(PROCESSING 仍需查或重试)。
查询统一用 GET。平台收付通是 GET /v3/ecommerce/profitsharing/returnorders,sub_mchid 与 out_return_no 均必填,order_id / out_order_no 选填;普通商户与服务商是 GET /v3/profitsharing/return-orders。查询不到返回 404 RESOURCE_NOT_EXISTS——排障时先分清是「单号错了」还是「回退单根本没建成功」。
退款与回退没有强耦合,回退可以先于退款,也可以后于退款,由平台自行决定。二级商户余额充足时完全可以不回退、直接退款,这一点常被误解成「不回退就退不了款」。
五、B2b:顺序与 APIv3 相反
B2b 门店助手走的是另一套小程序服务端接口:
POST https://api.weixin.qq.com/retail/B2b/refundprofitsharing?access_token=ACCESS_TOKEN
语义是「已分账订单,在完成退款后,通过调用此接口,可将已分账的资金从分账接收方的账户回退给分账方」——先退款、再回退,和 APIv3 收付通文档里「先调此接口将已分账资金回退,再发起退款」正好相反。把 APIv3 的调用顺序照搬到 B2b,会卡在退款单不存在或状态不符。
参数是 out_trade_no、out_refund_no、payee_type、payee_id、mchid、refund_amt(单位分)。限制更严:单笔退款单对单个分账接收方只能回退一次。对应错误码 10044(分账回退金额超过分账时金额)、10045(该退款单已发起过第三方分账回退)。
退款金额的扣款账户由订单状态决定:订单标记为需要分账时,全额退款要先调「完成分账」把剩余冻结资金从待结算金额解冻至可提现金额,且可提现金额余额 ≥ 退款金额;部分退款且金额 ≤ 订单未分账冻结金额时,直接从待结算金额账户退;订单已完结分账时,全额与部分退款都要求可提现金额充足。
六、curl 复现(收付通请求 + 查询)
# 1. 请求分账回退:return_mchid 是原分账接收方(出钱),sub_mchid 是回退接收商户(收钱)
curl -X POST 'https://api.mch.weixin.qq.com/v3/ecommerce/profitsharing/returnorders' \
-H 'Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900000109",nonce_str="5K8264ILTKCH16CQ",signature="<签名>",timestamp="1710000000",serial_no="<证书序列号>"' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"sub_mchid": "1900000109",
"order_id": "3008450740201411110007820472",
"out_return_no": "R20240301001",
"return_mchid": "1900000110",
"amount": 100,
"description": "订单退款前分账回退",
"transaction_id": "4200001234202403011234567890"
}'
# 2. 查询回退结果:sub_mchid + out_return_no 必填
curl -G 'https://api.mch.weixin.qq.com/v3/ecommerce/profitsharing/returnorders' \
--data-urlencode 'sub_mchid=1900000109' \
--data-urlencode 'out_return_no=R20240301001' \
-H 'Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900000109",nonce_str="5K8264ILTKCH16CQ",signature="<签名>",timestamp="1710000000",serial_no="<证书序列号>"' \
-H 'Accept: application/json'
order_id 与 out_order_no 二选一,不要都填。
七、幂等落库的伪代码
核心三条:按 out_return_no 落库;PROCESSING 用同号重发;FAILED 换号并把 fail_reason 一起留下来。
public function returnProfitSharing(array $req): array
{
// $req: sub_mchid, order_id|out_order_no, out_return_no, return_mchid,
// amount, description, transaction_id(>6个月必填)
$row = $this->repo->findByOutReturnNo($req['sub_mchid'], $req['out_return_no']);
if ($row && $row['result'] === 'SUCCESS') {
return $row; // 幂等直返,不再打微信
}
if ($row && $row['result'] === 'FAILED') {
// 终态失败才换号;旧号 + fail_reason 归档,便于对账
$this->repo->archive($row);
$req['out_return_no'] = $this->nextReturnNo($req['out_return_no']);
}
// $row 为 null 或 PROCESSING:都沿用原 out_return_no
$resp = $this->wxpay->post('/v3/ecommerce/profitsharing/returnorders', $req);
$this->repo->save([
'sub_mchid' => $req['sub_mchid'],
'out_return_no' => $req['out_return_no'],
'return_no' => $resp['return_no'] ?? null,
'amount' => $resp['amount'] ?? $req['amount'],
'result' => $resp['result'], // PROCESSING / SUCCESS / FAILED
'fail_reason' => $resp['fail_reason'] ?? null,
'finish_time' => $resp['finish_time'] ?? null,
]);
return $resp;
}
// 定时任务:扫 PROCESSING 且超过 5 分钟未更新的单,先查询、再同号重发;
// 超过 5 天自然会被微信置为 FAILED(TIME_OUT_CLOSED),此时走换号逻辑。
429 FREQUENCY_LIMITED 与 401 SIGN_ERROR 都不算终态失败,重试时不要更换商户回退单号。
项目信息
- 请求分账回退(平台收付通):https://pay.weixin.qq.com/doc/v3/partner/4012477737
- 查询分账回退结果(平台收付通):https://pay.weixin.qq.com/doc/v3/partner/4012477740
- V2 分账回退:https://pay.weixin.qq.com/doc/v2/merchant/4011984166
- B2b 门店助手 refundprofitsharing:https://developers.weixin.qq.com/miniprogram/dev/server/API/B2b/bill/api_refundprofitsharing.html
下一篇可切入的差异点:分账回退与退款的先后顺序颠倒之后,分账单 FINISHED、回退单 SUCCESS、退款单三个状态在日终对账时如何错位,以及按 out_return_no 与 return_no 双键核对时的具体步骤。