请求分账

更新时间:2025.01.07

微信订单支付成功后,商户发起分账请求,将结算后的资金分到分账接收方。

注意:

  • 对同一笔订单最多能发起50次分账请求,每次请求最多分给50个接收方;

  • 此接口采用异步处理模式,即在接收到商户请求后,会先受理请求再异步处理,最终的分账结果可以通过查询分账结果API获取;

  • 此接口支持商户对同一笔订单发起多次分账,请仔细阅读请求参数中的unfreeze_unsplit字段描述,执行相应操作(可参考文档后补充的调用样例);

  • 通过本接口解冻给出资方执行出境的金额,将和非分账订单金额一起参与轧差结算,与商户的结算合同中的结算周期、起结点等提现规则保持一致;

  • 出资方指和微信支付发生实际结算、资金入账的商户;在境外机构商模式下为机构商户、在服务商模式下为二级商户。

  • 商户上送敏感信息时使用微信支付平台公钥加密,证书序列号包含在请求HTTP头部的Wechatpay-Serial,详见接口规则


1. 接口说明

适用对象: 直连模式 机构模式

请求URL:https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/orders

请求方式:post

 

Path 指该参数为路径参数

Query 指该参数为URL参数

Body 指该参数需在请求JSON传参

 

2. 请求参数

参数名

变量

类型[长度限制]

必填

描述

二级商户号

sub_mchid

string[1, 32]

Body 微信支付分配的商户号,请与微信支付订单的二级商户号保持一致。(直连商户不需要,服务商/机构模式下必填)
示例值:1900000109

公众账号ID

appid

string[1, 32]

Body 微信分配的商户公众账号ID,分账接收方类型包含PERSONAL_OPENID时必填。
示例值:wx8888888888888888

二级商户公众账号ID

sub_appid

string[1, 32]

Body 微信分配的二级商户公众账号ID,分账接收方类型包含PERSONAL_SUB_OPENID时必填。
示例值:wx8888888888888889

微信支付订单号

transaction_id

string[1, 32]

Body 微信支付订单号
示例值:4208450740201411110007820472

商户分账单号

out_order_no

string[1,64]

Body 商户系统内部的分账单号,在商户系统内部唯一。只能是数字、大小写字母_-。
注:该单号用于标识商户侧发起的不同分账指令请求(包括请求分账API/解冻剩余资金API)。
若需要对同一笔微信支付订单进行多次资金分发处理,请注意更换【商户分账单号】后再发起调用,否则会被微信支付服务视为同一请求重入。
示例值:P20150806125346

分账接收方列表

receivers

array[1,50]

Body 分账接收方列表,若unfreeze_unsplit=false,则可以设置出资商户作为分账接受方,否则会拒绝分账请求。最多可有50个分账接收方。

分账接收方列表

是否解冻剩余未分账资金

unfreeze_unsplit

boolean

Body 1、如果为true,该笔订单剩余未分账的金额会解冻回分账出资方商户,并发起购汇出境;
         2、如果为false,该笔订单剩余未分账的金额不会解冻回分账出资方商户,可以对该笔订单再次进行分账。
示例值:true

请求示例

场景一

商户只需调用一次请求分账接口,即可完成对微信支付订单资金的分发
一笔支付订单金额10元,结算扣除手续费后剩余待分账金额为9.95元,此时商户可通过【分账请求API】发起分账请求
a. 指定分给合作商户(2480248971)0.99元
b. 分给合作用户(of8YZ9LPmjDmYAddobIvtTdQQjR8)0.99元
c. 同时通过设置unfreeze_unsplit为true,将剩余金额解冻给出资方执行购汇出境。来完成对本次订单的资金分发。

场景一:JSON

1{
2    "appid": "wx7bc98d929da735fe",
3    "out_order_no": "MCH13SFDG234155321146",
4    "receivers": [
5      {
6        "account": "2480248971",
7        "amount": 99,
8        "currency": "CNY",
9        "description": "分给xxx商户-10%",
10        "type": "MERCHANT_ID"
11      },
12      {
13        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
14        "amount": 99,
15        "currency": "CNY",
16        "description": "分给xxx用户-10%",
17        "type": "PERSONAL_OPENID"
18      }
19    ],
20    "sub_mchid": "999968479",
21    "transaction_id": "4200000012202203235765130087",
22    "unfreeze_unsplit": true
23}

场景二

商户根据自身需求对同一笔微信支付订单拆分进行多次分账
一笔支付订单金额200元,结算扣除手续费后剩余待分账金额为199元,商户希望先对其中50%的资金(100元)进行分账处理,此时商户可通过【分账请求API】发起分账请求
a. 指定分给合作商户(2480248971) 10元;
b. 分给合作用户(of8YZ6LPmjDmYAqdobIvwTdQQjR8) 10元;
c. 设置unfreeze_unsplit为false(不解冻剩余金额,表示后续还需执行分账动作),同时指定出资方为接收方账户,解冻80元回出资方账户参与当日轧差结算。

场景二:JSON

1{
2    "appid": "wx7bc98d929da735fe",
3    "out_order_no": "MCH1349FG041421146",
4    "receivers": [
5      {
6        "account": "2480248971",
7        "amount": 1000,
8        "currency": "CNY",
9        "description": "子单一:分给xxx商户",
10        "type": "MERCHANT_ID"
11      },
12      {
13        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
14        "amount": 1000,
15        "currency": "CNY",
16        "description": "子单一:分给xxx用户",
17        "type": "PERSONAL_OPENID"
18      },
19      {
20        "account": "999952224", # 注:这里填出资方商户号
21        "amount": 8000,
22        "currency": "CNY",
23        "description": "子单一:解冻出境",
24        "type": "MERCHANT_ID"
25      }
26    ],
27    "sub_mchid": "999968479",
28    "transaction_id": "4200000028202203236604547485",
29    "unfreeze_unsplit": false
30}

 

3. 返回参数

参数名

变量

类型[长度限制]

必填

描述

二级商户号

sub_mchid

string[1, 32]

微信支付分配的商户号
示例值:1900000109

微信支付订单号

transaction_id

string[1, 32]

微信支付订单号
示例值:4208450740201411110007820472

商户分账单号

out_order_no

string[1, 64]

商户分账单号,同请求入参。
示例值:P20150806125346

微信分账单号

order_id

string[1, 64]

微信分账单号,微信系统返回的唯一标识。
示例值:3008450740201411110007820472

分账单状态

state

string

分账单状态(每个接收方的分账结果请查看receivers中的result字段)。
PROCESSING:处理中,
FINISHED:分账完成,
示例值:FINISHED

分账接收方列表

receivers

array[1,50]

分账接收方列表
商户在发起分账请求或解冻剩余资金请求时,对同一笔订单可分给多个接收方(包括解冻给出资方),分账明细描述了每笔分给一个接收方的资金的状态。

分账接收方列表

返回示例

场景一返回结果

1{
2    "order_id": "7100000751202203238026613597498",
3    "out_order_no": "MCH13SFDG234155321146",
4    "receivers": [
5      {
6        "account": "999952224",  # 注:该账户为出资方商户号
7        "amount": 797,
8        "create_time": "2022-03-23T17:10:13+08:00",
9        "currency": "CNY",
10        "description": "Unfreeze the remaining funds to sponsor",
11        "detail_id": "7200000751202203238026613597602",
12        "detail_type": "UNFREEZE_TO_SPONSOR",
13        "rate_value": 83640300,
14        "result": "PENDING",
15        "settlement_amount": 952,
16        "settlement_currency": "HKD",
17        "type": "MERCHANT_ID"
18      },
19      {
20        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
21        "amount": 99,
22        "create_time": "2022-03-23T17:10:13+08:00",
23        "currency": "CNY",
24        "description": "分给xxx用户-10%",
25        "detail_id": "7200000751202203238026613597699",
26        "detail_type": "DISTRIBUTE_TO_OTHERS",
27        "result": "PENDING",
28        "type": "PERSONAL_OPENID"
29      },
30      {
31        "account": "2480248971",
32        "amount": 99,
33        "create_time": "2022-03-23T17:10:13+08:00",
34        "currency": "CNY",
35        "description": "分给xxx商户-10%",
36        "detail_id": "7200000751202203238026613597767",
37        "detail_type": "DISTRIBUTE_TO_OTHERS",
38        "result": "PENDING",
39        "type": "MERCHANT_ID"
40      }
41    ],
42    "state": "PROCESSING",
43    "sub_mchid": "999968479",
44    "transaction_id": "4200000012202203235765130087"
45  }    

场景二返回结果

1{
2    "order_id": "7100000749202203238028118660977",
3    "out_order_no": "MCH1349FG041421146",
4    "receivers": [
5      {
6        "account": "999952224",
7        "amount": 8000,
8        "create_time": "2022-03-23T17:35:18+08:00",
9        "currency": "CNY",
10        "description": "子单一:解冻出境",
11        "detail_id": "7200000749202203238028118661068",
12        "detail_type": "UNFREEZE_TO_SPONSOR",
13        "rate_value": 83640300,
14        "result": "PENDING",
15        "settlement_amount": 9564,
16        "settlement_currency": "HKD",
17        "type": "MERCHANT_ID"
18      },
19      {
20        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
21        "amount": 1000,
22        "create_time": "2022-03-23T17:35:18+08:00",
23        "currency": "CNY",
24        "description": "子单一:分给xxx用户",
25        "detail_id": "7200000749202203238028118661146",
26        "detail_type": "DISTRIBUTE_TO_OTHERS",
27        "result": "PENDING",
28        "type": "PERSONAL_OPENID"
29      },
30      {
31        "account": "2480248971",
32        "amount": 1000,
33        "create_time": "2022-03-23T17:35:18+08:00",
34        "currency": "CNY",
35        "description": "子单一:分给xxx商户",
36        "detail_id": "7200000749202203238028118661205",
37        "detail_type": "DISTRIBUTE_TO_OTHERS",
38        "result": "PENDING",
39        "type": "MERCHANT_ID"
40      }
41    ],
42    "state": "PROCESSING",
43    "sub_mchid": "999968479",
44    "transaction_id": "4200000028202203236604547485"
45  }  


4. 错误码

状态码

错误码

描述

解决方案

400

INVALID_REQUEST

用户类型为PERSONAL_OPENID,参数appid未设置

用户类型为PERSONAL_OPENID,请设置appid字段

400

INVALID_REQUEST

用户类型为PERSONAL_SUB_OPENID,参数sub_appid未设置

用户类型为PERSONAL_SUB_OPENID,请设置sub_appid字段

400

INVALID_REQUEST

用户OpenID和传入的AppID不匹配

请校验OpenID是在哪个商户的授权场景下所获取,并参照API文档中的分账接收方类型字段说明,设置相应AppID字段

400

INVALID_REQUEST

请求分账时,分账接收方列表中有重复账户

请检查分账接收方列表,去除同一次分账请求中的重复账户后再执行请求

400

INVALID_REQUEST

个人接收方选择传入姓名字段但未确认用户授权状态

若选择传入个人接收方姓名以执行用户实名信息一致性校验,需要商户先获取用户授权,并设置authorized字段为true

400

INVALID_REQUEST

请求分账时,个人接收方在微信侧的实名信息与传入的姓名字段值不一致

请和接收方用户确认实名信息无误后,再执行请求

400

INVALID_REQUEST

目前分账币种只支持CNY

请检查分账接收方列表,将分账币种调整为CNY之后再执行请求

400

INVALID_REQUEST

该订单已经超过最大可分账时间期限

请重新检查订单支付时间, 超过最大可分账时间期限的订单不允许再发起分账(已经由系统发起解冻购汇出境)

400

INVALID_REQUEST

该订单不支持分账

请检查微信支付订单号是否填错,并确认在调用下单API之前执行调用分账标记API成功

400

INVALID_REQUEST

请求的商户信息与原支付订单商户信息不一致

请仔细检查订单号是否填错、二级子商户是否未填或填错

400

INVALID_REQUEST

若选择解冻剩余未分金额(即在分账请求中设置unfreeze_unsplit为true),不能添加出资方为接收方

若选择解冻剩余金额(即在分账请求中设置unfreeze_unsplit为true),请移除分账接收方列表中的出资方账户后再执行请求

400

INVALID_REQUEST

若选择部分解冻时,解冻资金对应的账户填写错误(应设置为实际出资方)

请将出资方设置为真正出账的微信账户,机构商请填写机构商户号,服务商请填写子商户号

400

INVALID_REQUEST

请求分账时校验到分账接收关系不存在,请检查所有接收方是否已添加

请检查所有接收方是否已添加

400

INVALID_REQUEST

请求分账时校验到分账接收关系未生效或已解除,请检查所有接收方状态是否为生效中

请检查所有接收方状态是否为生效中

403

USER_ERROR

接收方列表中存在某接收方用户未实名认证,其微信零钱账户无法接受入金请求

请检查分账接收方列表,确认接收方用户均已通过微信实名认证后再发起请求

403

USER_ERROR

接收方列表中存在某接收方用户账户被限制收款,其零钱账户累计收款额度+本次收款金额已超过限制

若出现用户入账限额场景,被限额的用户会收到微信推送消息,请引导接收方用户根据指引完成升级后再发起分账

403

USER_ERROR

接收方列表中存在某接收方用户账户命中微信侧风险拦截策略,其零钱账户被限制收款

被平台侧提示风险拦截的用户,被全场景限制收款,请剔除相应风险接收方后再发起分账请求

403

NO_AUTH

商户未签约境外分账产品能力

请参考产品流程和接入准备,确认商户具有分账权限后再发起请求

403

NO_AUTH

商户已开通分账产品能力,等待生效中(一般为第二天才生效)

开通分账产品能力当天不能发起分账,请等待第二天后发起请求

403

NO_AUTH

分账接收方境外权限被处罚

请确认分账接收方均合法合规后,请发起分账请求

403

NO_AUTH

商户父子关系不存在,请使用正确的二级商户号发起请求

请检查二级商户号(sub_mchid)是否填写正确

400

INVALID_REQUEST

商户请求分账时指令(out_order_no)已存在,且接收方与现有分账指令不一致

若为同一分账请求,请校验接收方信息是否一致;若为不同分账请求,请更换外部指令单号(out_order_no)再发起分账请求

400

INVALID_REQUEST

商户请求分账时指令(out_order_no)已存在,且分账金额与现有指令不一致

若为同一分账请求,请校验接收方列表中的分账金额是否一致;若为不同分账请求,请更换外部指令单号(out_order_no)再发起分账请求

400

INVALID_REQUEST

商户请求分账时指令(out_order_no)已存在,但转账明细数量不一致

若为同一分账请求,请校验接收方列表是否一致;若为不同分账请求,请更换外部指令单号(out_order_no)再发起分账请求

400

INVALID_REQUEST

商户解冻剩余资金时指令(out_order_no)已存在,且明细内容不符合预期

若为不同分账请求,请更换外部指令单号(out_order_no)再发起分账请求

400

INVALID_REQUEST

请求分账解冻出境时外币结算金额不能为0

请适当调整对应的解冻人民币金额,使得兑换成外币后的外币金额大于0

400

INVALID_REQUEST

请求分账时分出金额超过最大比例

请调整分出金额至分出比例上限以内后再发起分账请求

400

INVALID_REQUEST

该订单已经超过最大分账次数限制,不能再发起分账

请直接调用【解冻剩余金额API】执行解冻

403

NOT_ENOUGH

请求分账时校验到可分金额不足

可通过【查询剩余待分金额API】来获取订单当前的可分金额

500

SYSYTEM_ERROR

商户发起分账请求指定的微信支付订单资金冻结流程还未完成,请稍后重试

用户支付完成后即会触发对该笔分账支付单的资金冻结流程,建议商户可在3~5min后重试

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.