API字典 /分账 / 添加分账接收方API

添加分账接收方API

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

商户发起添加分账接收方请求，建立分账接收方列表。后续可通过发起分账请求，将分账方商户结算后的资金，分给该分账接收方。

注意：

1. 一份分账接收关系涉及分账方和接收方：
其中分账方是指【发起方商户】或【发起方商户和其二级商户】（直连商模式下为直连商户号；服务商模式或境外机构商模式下，为父商户号以及二级商户号）；
接收方是指接收分账资金的个人微信账号或商户号，商户在添加接收方信息时需提供接收方类型及接收方账号；

以境外机构商模式举例，机构商商户A下有两个二级商户A1和A2已经接入分账服务，其中B1是A1商户的合作方，B2是A2商户的合作方；
——此时机构商A为了实现A1商户的分账订单分账给B1，则需要添加以下分账关系：mchid:A + sub_mchid: A1 + account: B1;
——为了实现A2商户的分账订单分账给B2，则需要添加：mchid:A + sub_mchid: A2 + account: B2;

2. 商户在发起添加分账接收方请求之前，需要先调用境外文件上传API来提交接收方商户的合作关系附件，以供微信进行分账接收关系的审核。请提前准备如下合作关系材料，若资料上传不齐全，可能审批不通过。
【合作关系材料说明】

a. 双方合作关系合同材料：
当分账接收方为境内企业，需提交跨境电商与分账接收方的合作合同的电子扫描件（必收）；当分账接收方为境内个人，针对每个二级商户（跨境电商）只需要提供一次跨境电商与某个境内个人合作关系证明的样例。

b. 分账接收方申请函，详见模板增加分账接收方承诺函。

注：支持2份证明材料分开提交，将两份资料分别使用文件上传API进行提交，获取到文件标识ID之后，填入【file_id】字段。

3. 调用本接口成功后，接收方关系状态为INIT。待微信审核接收方材料通过，接收方关系状态扭转为EFFECTIVE后，方可调用请求分账API接口来分给该接收方。可调用查询分账接收方添加结果API来确认分账接收方关系是否已经生效（审核完成）。

4. 若接收方关系审核失败，可根据审核失败原因字段提示，重新在文件上传API提交合规完整的审核材料后，重新发起添加接收方请求。注：INIT/EFFECTIVE状态下的分账接收方不允许再对该接收方发起添加请求。

1. 接口说明

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

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

请求方式：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
接收方类型	type	string	是	Body接收方类型。 MERCHANT_ID：商户号， PERSONAL_OPENID：个人OpenID，由商户APPID转换得到 PERSONAL_SUB_OPENID：是个人Sub_OpenID，由二级商户APPID转换得到示例值：MERCHANT_ID
接收方账号	account	string[1, 64]	是	Body类型是MERCHANT_ID时，是商户号类型是PERSONAL_OPENID时，是个人OpenID 类型是PERSONAL_SUB_OPENID时，是个人Sub_OpenID 示例值：86693852
分账接收方全称	name	string[1, 1024]	否	Body设置说明： 1. 注：此字段需要加密，加密方法详见文档开头的：敏感信息加密说明 2. 按照不同接收方类型，请按照如下说明进行设置： a. 分账接收方类型是MERCHANT_ID时，是商户全称（必传）； b. 分账接收方类型是PERSONAL_OPENID或PERSONAL_SUB_OPENID时，是个人姓名（选传，若传入则会校验该字段值与微信支付侧的实名信息是否一致，且需要设置authorized字段来确认是否获取用户信息授权）示例值：Merchant name
是否已经获取用户实名信息授权	authorized	boolean	否	Body商户向微信支付传输用户姓名及账户信息，微信支付后台将协助校验用户信息一致性，降低分账接收方填写错误的风险。该字段为商户确认传输的用户信息的授权状态： 1）false代表未获取用户授权，微信支付将拒绝接收数据 2）true代表已获取用户授权，微信支付将正常接收数据注意，当接收方类型为用户(PERSONAL_OPNEID/PERSONAL_SUB_OPENID)且选择传入账户名称(即name字段)时，该字段为必填项示例值：true
与分账方的关系类型	relation_type	string	是	Body分账商户与接收方的关系。 SUPPLIER：供应商， DISTRIBUTOR：分销商， TAX_SERVICE_PROVIDER：税费服务商， IT_SERVICE_PROVIDER：技术服务提供方， CUSTOM：自定义，示例值：SERVICE_PROVIDER
自定义的分账关系	custom_relation	string[1, 10]	否	Body分账方与接收方具体的关系，本字段最多10个字。当字段relation_type的值为CUSTOM时，本字段必填当字段relation_type的值不为CUSTOM时，本字段无需填写示例值：代理商
分账场景详细描述	scene	string[3, 256]	是	Body请商户对于分账场景进行具体描述。示例值：该分账接收方是境内税费服务提供方，帮助商户向境内海关代扣代缴税费。
接收方商户的主营业务范围	major_service	string[3, 256]	否	Body若接收方类型为MERCHANT_ID，该字段为必填项。请提交分账接收方的主要服务场景，以及发生分账场景的公开网页链接、小程序名称、公众号名称以及APPID（如有）。示例值：Tax preparation service, www.example.com, Mini program: WXG, APPID: wx8888888888888888
分账接收方预计分账比例	expected_ratio	int	是	Body指所添加的分账接收方预计可能达到的最高分账比例，此处仅作信息收集，不代表实际最高分账比例，实际允许的最高分账比例以平台策略为准。单位万分比，比如2000表示20%。示例值：2000
增加分账接收方申请函文件ID	application_file_id	string[10, 128]	否	Body请参考API开头的【材料提交方式说明】。增加分账接收方申请函对应的文件ID，请使用文件上传API进行提交，获取到文件标识ID之后，再填入该字段。示例值：439d2325-f878-8960-8719-604ed42f1139
分账方与接收方合作关系证明文件ID	partnership_file_id	string[10, 128]	否	Body请参考API开头的【材料提交方式说明】。分账方与接收方合作关系证明对应的文件ID，若接收方类型为MERCHANT_ID，则该字段必填（若采用V1.0版本合并资料提交的方式则不做要求）；请使用文件上传API进行提交，获取到文件标识ID之后，再填入该字段。示例值：de851a06-5a38-9d31-a102-275a17c477de

请求示例

添加商户为接收方添加用户为接收方


{
    "account": "1900000109",
    "expected_ratio": 1000,
    "application_file_id": "439d2325-f878-8960-8719-604ed42f1139",
    "partnership_file_id": "de851a06-5a38-9d31-a102-275a17c477de",
    "major_service": "APPID: wx888888888888",
    "name": "tdcUez3ov/jAzO2sDwLap6uc8d2itP6ffhoQzOa9LDzrMOqz/+reA79+e3aijKn0dQ2tPA391byJY6VqSaPhCpDJgvoawBYCNxkPR+ID9SYq/axfI4hN66aO/d8PWcKyEV/4AuVJEJ3ZIhvJXfnkoxmP6vF3yv7g1zS/IL1dTHCqY4X2tTpko4BRylcfz2Fi82CLbSegaB1h3SOsmstiC/wf2MM5rSnamgTAKA0a7w5+0QsvmNWbU9pVkOnHCGTGLUQFpDMpDvMtJS/f8vrrCPAeJa6ijwF7WLOqTV3cVWFYAtSC3iSDGyD7p2axHqsrirJo8fq63lYSRrTia1vgnA==",
    "relation_type": "TAX_SERVICE_PROVIDER",
    "scene": "该分账接收方是境内税费服务提供方，帮助商户向境内海关代扣代缴税费。",
    "sub_mchid": "999968480",
    "type": "MERCHANT_ID"
  }


{
    "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8", 
    "appid": "wx78898sdfwe9888835", 
    "relation_type": "CUSTOM", 
    "custom_relation": "特约主播", 
    "expected_ratio": 800, 
    "scene": "该分账接收方为特约带货主播", 
    "name": "tdcUez3ov/jAzO2sDwLap6uc8d2itP6ffhoQzOa9LDzrMOqz/+reA79+e3aijKn0dQ2tPA391byJY6VqSaPhCpDJgvoawBYCNxkPR+ID9SYq/axfI4hN66aO/d8PWcKyEV/4AuVJEJ3ZIhvJXfnkoxmP6vF3yv7g1zS/IL1dTHCqY4X2tTpko4BRylcfz2Fi82CLbSegaB1h3SOsmstiC/wf2MM5rSnamgTAKA0a7w5+0QsvmNWbU9pVkOnHCGTGLUQFpDMpDvMtJS/f8vrrCPAeJa6ijwF7WLOqTV3cVWFYAtSC3iSDGyD7p2axHqsrirJo8fq63lYSRrTia1vgnA==",
    "authorized":true,
    "sub_mchid": "999968480",
    "type": "PERSONAL_OPENID"
}

3. 返回参数

参数名	变量	类型[长度限制]	必填	描述
二级商户号	sub_mchid	string[1, 32]	否	二级商户号，同请求入参。示例值：1900000109
接收方类型	type	string	是	接收方类型，同请求入参。 MERCHANT_ID：商户号， PERSONAL_OPENID：个人OpenID，由商户APPID转换得到 PERSONAL_SUB_OPENID：个人Sub_OpenID，由二级商户APPID转换得到示例值：MERCHANT_ID
接收方账号	account	string[1, 64]	是	接收方账号，同请求入参。示例值：86693852
分账接收方全称	name	string[1, 1024]	否	分账接收方全称，同请求入参。示例值：hu89ohu89ohu89o
与分账方的关系类型	relation_type	string	是	与分账方的关系类型，同请求入参。 SUPPLIER：供应商， DISTRIBUTOR：分销商， TAX_SERVICE_PROVIDER：税费服务商， IT_SERVICE_PROVIDER：技术服务提供方， CUSTOM：自定义，示例值：SUPPLIER
自定义的分账关系	custom_relation	string[1, 10]	否	自定义的分账关系，同请求入参。示例值：代理商
分账场景详细描述	scene	string[3, 256]	是	分账场景详细描述，同请求入参。示例值：该分账接收方是境内税费服务提供方，帮助商户向境内海关代扣代缴税费。
接收方商户的主营业务范围	major_service	string[3, 256]	否	若接收方类型为MERCHANT_ID，该字段为必填项。请提交分账接收方的主要服务场景，以及发生分账场景的公开网页链接、小程序名称、公众号名称以及APPID（如有）。示例值：Tax preparation service, www.example.com, Mini program: WXG, APPID: wx8888888888888888
分账接收方预计分账比例	expected_ratio	int	是	分账接收方预计分账比例，同请求入参。示例值：2000
接收方关系状态	state	string	是	分账方与该接收方的关系状态，仅允许对EFFECTIVE的接收方发起分账。 INIT：待审核，等待微信审核接收方资料 EFFECTIVE：生效中，接收方关系生效中 AUDIT_FAILED：审核未通过，接收方审核未通过示例值：AUDIT_FAILED
接收关系添加失败原因	fail_reason	string	否	添加分账接收方失败的原因，只有在state为AUDIT_FAILED时才会出现 PARTNERSHIP_NOT_SUPPORTED：合作关系不支持，分账接收方合作关系不支持分账 DEFAULT_ERROR：默认错误，示例值：PARTNERSHIP_NOT_SUPPORTED
添加接收方失败的原因描述	fail_description	string[0, 2048]	否	只有当state为AUDIT_FAILED时，才会出现添加接收方失败原因的详细说明。请参考描述中的反馈和建议，修改您的请求并重新添加接收方。示例值：合作证书没有盖章，也不是原始版本的彩色扫描件。
增加分账接收方申请函文件ID	application_file_id	string[10, 128]	否	增加分账接收方申请函对应的文件ID 示例值：439d2325-f878-8960-8719-604ed42f1139
分账方与接收方合作关系证明文件ID	partnership_file_id	string[10, 128]	否	分账方与接收方合作关系证明文件ID 示例值：de851a06-5a38-9d31-a102-275a17c477de

返回示例

正常示例


{
    "account":"of8YZ6LPmjDmYAqdobIvwTdQQjR8",
    "custom_relation":"特约主播",
    "expected_ratio":800,
    "relation_type":"CUSTOM",
    "scene":"该分账接收方为特约带货主播",
    "state":"INIT",
    "type":"PERSONAL_OPENID"
}


{
    "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8", 
    "type": "PERSONAL_OPENID"
}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

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	若接收方类型为MERCHANT_ID，请在name字段设置接收方商户全称	若接收方类型为MERCHANT_ID，请在name字段设置接收方商户全称
400	INVALID_REQUEST	若接收方类型为MERCHANT_ID，请在major_service字段设置接收方商户的主营业务范围	若接收方类型为MERCHANT_ID，请在major_service字段设置接收方商户的主营业务范围
400	INVALID_REQUEST	若接收方关系类型为CUSTOM时，请设置custom_relation字段	若接收方关系类型为CUSTOM时，请设置custom_relation字段
400	INVALID_REQUEST	个人接收方选择传入姓名字段但未确认用户授权状态	若选择传入个人接收方姓名以执行用户实名信息一致性校验，需要商户先获取用户授权，并设置authorized字段为true
400	INVALID_REQUEST	个人接收方在微信侧的实名信息与传入的姓名字段值不一致	请和接收方用户确认实名信息无误后，再执行请求
400	INVALID_REQUEST	已经存在一条分账接收方方关系记录，且预期最大分出比例（expected_ratio）与本次请求不符	请检查账户及预期最大分出比例是否填写正确，若已经添加过该接收方，可通过【查询分账接收方添加结果API】查询结果
400	INVALID_REQUEST	已经存在一条分账接收方关系记录，且上传的双方合作关系合同文件ID字段（partnership_file_id）与本次请求不符	请检查账户及双方合作关系合同文件ID字段（partnership_file_id）是否填写正确，若已经添加过该接收方，可通过【查询接收方添加结果API】查询结果
400	INVALID_REQUEST	已经存在一条分账接收方关系记录，且上传的分账接收方申请函文件ID字段（application_file_id）与本次请求不符	请检查账户及分账接收方申请函文件ID字段（application_file_id）是否填写正确，若已经添加过该接收方，可通过【查询接收方添加结果API】查询结果
403	NO_AUTH	商户未签约境外分账产品能力	请参考产品流程和接入准备，确认商户具有分账权限后再发起请求
403	NO_AUTH	商户已开通分账产品能力，等待生效中(一般为第二天才生效)	开通分账产品能力当天不能发起分账，请等待第二天后发起请求
403	NO_AUTH	商户父子关系不存在，请使用正确的二级商户号发起请求	请检查二级商户号(sub_mchid)是否填写正确

页面导航

语言

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

支付产品

资金类产品

其他产品

添加分账接收方API

1. 接口说明

2.请求参数

请求示例

3. 返回参数

返回示例

4. 错误码