编程 分账回退:sub_mchid 是钱回来的一方,PROCESSING 换回退单号就是二次出款

2026-11-19 00:04:07

分账回退排障: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 也明确「不支持回退给自己,分账回退出资商户不允许和接收商户相同」。

二、能发起回退的前提

四道过滤条件,缺一不可:

  1. 接收方类型为 MERCHANT_ID(商户号)。分账给个人的分账单不支持回退。
  2. 分账单状态 FINISHED(处理完成),且分账结果 result=SUCCESS。
  3. 接收方已在商户平台-交易中心-分账-分账接收设置下开启「同意分账回退」,否则 403 NO_AUTH,报错文案是「回退方未开通分账回退功能」。平台收付通文档另有一句:商户类型的接收方自动开通了分账回退,可以直接调接口。遇到 NO_AUTH 时,先按实际接口族核对这条开关,不要只依据文档里那句「自动开通」。
  4. 时间窗 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 文档给的处置是「请降低频率后原单重试,请勿更换商户回退单号」——限流不是失败,不构成换号理由。

四、三套接口族的前提差异

接口族请求方向字段特有前提
普通商户 APIv3POST /v3/profitsharing/return-ordersreturn_mchid请求体无 sub_mchid
服务商 APIv3同上return_mchidsub_mchid 为特约商户号;接收方需开启同意分账回退
平台收付通 APIv3POST /v3/ecommerce/profitsharing/returnordersreturn_mchid + sub_mchidsub_mchid 必填,指回退接收商户
V2POST https://api.mch.weixin.qq.com/secapi/pay/profitsharingreturnreturn_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 双键核对时的具体步骤。

推荐文章

程序员茄子在线接单