添加分账接收方
更新时间:2025.03.21商户发起添加分账接收方请求,建立分账接收方列表。后续可通过发起分账请求,将分账方商户结算后的资金,分给该分账接收方。
|
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 微信支付分配的商户号,请与微信支付订单的二级商户号保持一致。(直连商户不需要,服务商/机构模式下必填) |
公众账号ID | appid | string[1, 32] | 否 | Body 微信分配的商户公众账号ID,分账接收方类型包含PERSONAL_OPENID时必填。 |
二级商户公众账号ID | sub_appid | string[1, 32] | 否 | Body 微信分配的二级商户公众账号ID,分账接收方类型包含PERSONAL_SUB_OPENID时必填。 |
接收方类型 | type | string | 是 | Body 接收方类型。 |
接收方账号 | account | string[1, 64] | 是 | Body 类型是MERCHANT_ID时,是商户号 |
分账接收方全称 | name | string[1, 1024] | 否 | Body 设置说明:
a. 分账接收方类型是MERCHANT_ID时,是商户全称(必传); |
是否已经获取用户实名信息授权 | authorized | boolean | 否 | Body 商户向微信支付传输用户姓名及账户信息,微信支付后台将协助校验用户信息一致性,降低分账接收方填写错误的风险。该字段为商户确认传输的用户信息的授权状态: |
与分账方的关系类型 | relation_type | string | 是 | Body 分账商户与接收方的关系。 |
自定义的分账关系 | custom_relation | string[1, 10] | 否 | Body 分账方与接收方具体的关系,本字段最多10个字。 |
分账场景详细描述 | scene | string[3, 256] | 是 | Body 请商户对于分账场景进行具体描述。 |
接收方商户的主营业务范围 | major_service | string[3, 256] | 否 | Body 若接收方类型为MERCHANT_ID,该字段为必填项。请提交分账接收方的主要服务场景,以及发生分账场景的公开网页链接、小程序名称、公众号名称以及APPID(如有)。 |
分账接收方预计分账比例 | expected_ratio | int | 是 | Body 指所添加的分账接收方预计可能达到的最高分账比例,此处仅作信息收集,不代表实际最高分账比例,实际允许的最高分账比例以平台策略为准。 |
增加分账接收方申请函文件ID | application_file_id | string[10, 128] | 否 | Body 请参考API开头的【材料提交方式说明】。增加分账接收方申请函对应的文件ID,请使用文件上传API进行提交,获取到文件标识ID之后,再填入该字段。 |
分账方与接收方合作关系证明文件ID | partnership_file_id | string[10, 128] | 否 | Body 请参考API开头的【材料提交方式说明】。分账方与接收方合作关系证明对应的文件ID,若接收方类型为MERCHANT_ID,则该字段必填(若采用V1.0版本合并资料提交的方式则不做要求);请使用文件上传API进行提交,获取到文件标识ID之后,再填入该字段。 |
请求示例
添加商户为接收方
添加用户为接收方
3. 返回参数
参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
---|---|---|---|---|
二级商户号 | sub_mchid | string[1, 32] | 否 | 二级商户号,同请求入参。 |
接收方类型 | type | string | 是 | 接收方类型,同请求入参。 |
接收方账号 | account | string[1, 64] | 是 | 接收方账号,同请求入参。 |
分账接收方全称 | name | string[1, 1024] | 否 | 分账接收方全称,同请求入参。 |
与分账方的关系类型 | relation_type | string | 是 | 与分账方的关系类型,同请求入参。 |
自定义的分账关系 | custom_relation | string[1, 10] | 否 | 自定义的分账关系,同请求入参。 |
分账场景详细描述 | scene | string[3, 256] | 是 | 分账场景详细描述,同请求入参。 |
接收方商户的主营业务范围 | major_service | string[3, 256] | 否 | 若接收方类型为MERCHANT_ID,该字段为必填项。请提交分账接收方的主要服务场景,以及发生分账场景的公开网页链接、小程序名称、公众号名称以及APPID(如有)。 |
分账接收方预计分账比例 | expected_ratio | int | 是 | 分账接收方预计分账比例,同请求入参。 |
接收方关系状态 | state | string | 是 | 分账方与该接收方的关系状态,仅允许对EFFECTIVE的接收方发起分账。 |
接收关系添加失败原因 | fail_reason | string | 否 | 添加分账接收方失败的原因,只有在state为AUDIT_FAILED时才会出现 |
添加接收方失败的原因描述 | fail_description | string[0, 2048] | 否 | 只有当state为AUDIT_FAILED时,才会出现添加接收方失败原因的详细说明。请参考描述中的反馈和建议,修改您的请求并重新添加接收方。 |
增加分账接收方申请函文件ID | application_file_id | string[10, 128] | 否 | 增加分账接收方申请函对应的文件ID |
分账方与接收方合作关系证明文件ID | partnership_file_id | string[10, 128] | 否 | 分账方与接收方合作关系证明文件ID |
返回示例
正常示例
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)是否填写正确 |