微信订单支付成功后,商户发起分账请求,将结算后的资金分到分账接收方。
1. 接口说明
请求URL:https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/orders
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个分账接收方。 |
 | 分账接收方列表 | | |
分账币种 | currency | string[3, 3] | 是 | 分账币种,符合ISO 4217标准的三位字母代码,目前只支持人民币,"CNY"。 示例值:CNY | 分账接收方类型 | type | string[1, 32] | 是 | 分账接收方类型: MERCHANT_ID:商户号, PERSONAL_OPENID:个人OpenID,由商户APPID转换得到 PERSONAL_SUB_OPENID:是个人Sub_OpenID,由二级商户APPID转换得到 示例值:MERCHANT_ID | 分账接收方账号 | account | string[1, 64] | 是 | 1、类型是MERCHANT_ID时,是商户号 2、类型是PERSONAL_OPENID时,是个人OpenID 3、类型是PERSONAL_SUB_OPENID时,是是个人Sub_OpenID。 注意:当前不支持添加个人用户为接收方 示例值:86693852 | 分账个人接收方姓名 | name | string[1, 1024] | 否 | 可选项,在接收方类型为个人的时可选填。若有值,会检查 name 是否与微信用户实名相匹配,不匹配会拒绝分账请求 分账接收方类型是PERSONAL_OPENID或PERSONAL_SUB_OPENID时,是个人姓名的密文(选传,传则校验) ,此字段需要加密,加密方法详见文档开头的:敏感信息加密说明 示例值:hu89ohu89ohu89o | 是否已经获取用户实名信息授权 | authorized | boolean | 否 | 商户向微信支付传输用户姓名及账户信息,微信支付后台将协助校验用户信息一致性,降低分账接收方填写错误的风险。该字段为商户确认传输的用户信息的授权状态: 1)false代表未获取用户授权,微信支付将拒绝接收数据 2)true代表已获取用户授权,微信支付将正常接收数据 注意,在分账个人接收方姓名字段(即name字段)被设置时,该字段为必填项 示例值:true | 分账金额 | amount | int | 是 | 分账金额,单位为分; 只能为整数,不能超过原订单支付金额; 且在分给其他接收方的场景,还会校验分出金额是否超过最大分账比例金额。 示例值:888 | 分账描述 | description | string[1, 80] | 是 | 分账的原因描述,分账账单中需要体现 示例值:分给商户A |
|
|
是否解冻剩余未分账资金 | 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] | 是 | 分账接收方列表 商户在发起分账请求或解冻剩余资金请求时,对同一笔订单可分给多个接收方(包括解冻给出资方),分账明细描述了每笔分给一个接收方的资金的状态。 |
 | 分账接收方列表 | | |
分账币种 | currency | string[3, 3] | 是 | 分账币种,同请求入参。 示例值:CNY | 分账金额 | amount | int | 是 | 分账金额,同请求入参。 示例值:100 | 分账描述 | description | string[1, 80] | 是 | 商户传入的分账描述,同请求入参。 示例值:分给商户1900000110 | 接收方类型 | type | string[1, 32] | 是 | 接收方类型,同请求入参。 MERCHANT_ID:商户号, PERSONAL_OPENID:个人OpenID,由商户APPID转换得到 PERSONAL_SUB_OPENID:是个人Sub_OpenID,由二级商户APPID转换得到 示例值:MERCHANT_ID | 接收方账号 | account | string[1, 64] | 是 | 接收方账号,同请求入参。 示例值:1900000109 | 分账明细结果 | result | string[1, 32] | 是 | 每一笔分账明细转账的结果。 PENDING:待分账, SUCCESS:分账成功, CLOSED:已关闭, 示例值:SUCCESS | 分账明细失败原因 | fail_reason | string[1, 64] | 否 | 分账明细失败原因。在分账明细结果为"CLOSED"时才会被设置。 NO_RELATION:分账关系已解除, SUB_MERCHANT_FRONEN:二级商户被冻结, MCH_CONTRACT_SETTLE_OFF:商户结算合同为关闭结算状态, MCH_CONTRACT_FROZEN:商户结算合同被冻结, ACCOUNT_ABNORMAL:分账接收账户异常, RECEIVER_HIGH_RISK:高风险接收方, RECEIVER_REAL_NAME_NOT_VERIFIED:接收方未实名, NO_AUTH:分账权限已解除, DEFAULT_ERROR:默认错误, 示例值:ACCOUNT_ABNORMAL | 分账明细创建时间 | create_time | string[1, 64] | 是 | 分账明细创建时间,遵循RFC3339标准格式 示例值:2015-05-20T13:29:35.120+08:00 | 分账明细完成时间 | finish_time | string[1, 64] | 否 | 分账明细完成时间,遵循RFC3339标准格式。在分账明细结果为"SUCCESS"或"CLOSED"时才会被设置。 示例值:2015-05-20T13:29:35.120+08:00 | 分账明细单号 | detail_id | string[1, 64] | 是 | 微信分账明细单号,每笔分账业务执行的明细单号。 示例值:36011111111111111111111 | 分账明细类型 | detail_type | string[1, 32] | 是 | 分账明细分为两类,包括分出给其他接收方和解冻给出资方。可由该字段来区分,若明细类型为UNFREEZE_TO_SPONSOR(解冻给出资方)时,分账明细中还会返回出资方结算币种、结算金额、汇率值等信息。 DISTRIBUTE_TO_OTHERS:分出给其他接收方, UNFREEZE_TO_SPONSOR:解冻给出资方出境, 示例值:DISTRIBUTE_TO_OTHERS | 出资方结算币种 | settlement_currency | string[3, 3] | 否 | 出资方的结算币种,明细类型为UNFREEZE_TO_SPONSOR(解冻给出资方)时该字段才会被设置。 示例值:HKD | 出资方结算金额 | settlement_amount | int | 否 | 该笔明细通过换汇后最终结算给出资方的金额,采用最小币种单位。 示例值:110 | 汇率值 | rate | int | 否 | 分账币种与结算币种的兑换比例乘以10的8次方即为此值。 若分账币种与结算币种均为人民币,则兑换比值为1,汇率值为100,000,000; 若结算币种为美元,假设美元兑换人民币的比例为6.5,则汇率值为650,000,000。 示例值:81000000 |
|
|
返回示例
场景一返回结果

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后重试 |