API字典 / 分账 / 分账标记API

请求分账API

最新更新时间：2022.08.04 版本说明

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

注意：

• 对同一笔订单最多能发起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个分账接收方。

参数名	变量	类型[长度限制]	必填	描述
分账币种	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

是

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

请求示例

场景一场景二

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

场景一：JSON 场景二：JSON


{
    "appid": "wx7bc98d929da735fe",
    "out_order_no": "MCH13SFDG234155321146",
    "receivers": [
      {
        "account": "2480248971",
        "amount": 99,
        "currency": "CNY",
        "description": "分给xxx商户-10%",
        "type": "MERCHANT_ID"
      },
      {
        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
        "amount": 99,
        "currency": "CNY",
        "description": "分给xxx用户-10%",
        "type": "PERSONAL_OPENID"
      }
    ],
    "sub_mchid": "999968479",
    "transaction_id": "4200000012202203235765130087",
    "unfreeze_unsplit": true
  }


{
    "appid": "wx7bc98d929da735fe",
    "out_order_no": "MCH1349FG041421146",
    "receivers": [
      {
        "account": "2480248971",
        "amount": 1000,
        "currency": "CNY",
        "description": "子单一：分给xxx商户",
        "type": "MERCHANT_ID"
      },
      {
        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
        "amount": 1000,
        "currency": "CNY",
        "description": "子单一：分给xxx用户",
        "type": "PERSONAL_OPENID"
      },
      {
        "account": "999952224", # 注：这里填出资方商户号
        "amount": 8000,
        "currency": "CNY",
        "description": "子单一：解冻出境",
        "type": "MERCHANT_ID"
      }
    ],
    "sub_mchid": "999968479",
    "transaction_id": "4200000028202203236604547485",
    "unfreeze_unsplit": false
  }

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

收起

返回示例

场景一返回结果场景二返回结果


{
    "order_id": "7100000751202203238026613597498",
    "out_order_no": "MCH13SFDG234155321146",
    "receivers": [
      {
        "account": "999952224",  # 注：该账户为出资方商户号
        "amount": 797,
        "create_time": "2022-03-23T17:10:13+08:00",
        "currency": "CNY",
        "description": "Unfreeze the remaining funds to sponsor",
        "detail_id": "7200000751202203238026613597602",
        "detail_type": "UNFREEZE_TO_SPONSOR",
        "rate_value": 83640300,
        "result": "PENDING",
        "settlement_amount": 952,
        "settlement_currency": "HKD",
        "type": "MERCHANT_ID"
      },
      {
        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
        "amount": 99,
        "create_time": "2022-03-23T17:10:13+08:00",
        "currency": "CNY",
        "description": "分给xxx用户-10%",
        "detail_id": "7200000751202203238026613597699",
        "detail_type": "DISTRIBUTE_TO_OTHERS",
        "result": "PENDING",
        "type": "PERSONAL_OPENID"
      },
      {
        "account": "2480248971",
        "amount": 99,
        "create_time": "2022-03-23T17:10:13+08:00",
        "currency": "CNY",
        "description": "分给xxx商户-10%",
        "detail_id": "7200000751202203238026613597767",
        "detail_type": "DISTRIBUTE_TO_OTHERS",
        "result": "PENDING",
        "type": "MERCHANT_ID"
      }
    ],
    "state": "PROCESSING",
    "sub_mchid": "999968479",
    "transaction_id": "4200000012202203235765130087"
  }


{
    "order_id": "7100000749202203238028118660977",
    "out_order_no": "MCH1349FG041421146",
    "receivers": [
      {
        "account": "999952224",
        "amount": 8000,
        "create_time": "2022-03-23T17:35:18+08:00",
        "currency": "CNY",
        "description": "子单一：解冻出境",
        "detail_id": "7200000749202203238028118661068",
        "detail_type": "UNFREEZE_TO_SPONSOR",
        "rate_value": 83640300,
        "result": "PENDING",
        "settlement_amount": 9564,
        "settlement_currency": "HKD",
        "type": "MERCHANT_ID"
      },
      {
        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
        "amount": 1000,
        "create_time": "2022-03-23T17:35:18+08:00",
        "currency": "CNY",
        "description": "子单一：分给xxx用户",
        "detail_id": "7200000749202203238028118661146",
        "detail_type": "DISTRIBUTE_TO_OTHERS",
        "result": "PENDING",
        "type": "PERSONAL_OPENID"
      },
      {
        "account": "2480248971",
        "amount": 1000,
        "create_time": "2022-03-23T17:35:18+08:00",
        "currency": "CNY",
        "description": "子单一：分给xxx商户",
        "detail_id": "7200000749202203238028118661205",
        "detail_type": "DISTRIBUTE_TO_OTHERS",
        "result": "PENDING",
        "type": "MERCHANT_ID"
      }
    ],
    "state": "PROCESSING",
    "sub_mchid": "999968479",
    "transaction_id": "4200000028202203236604547485"
  }

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

页面导航

语言

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

支付产品

资金类产品

其他产品

请求分账API

1. 接口说明

2. 请求参数

请求示例

3. 返回参数

返回示例

4. 错误码