Adding Receiver
Update Time:2025.03.21The merchant initiates a request to add receiver and create a receiver list. The settled funds of the merchant can be distributed to the receiver by requesting funds-distribution.
|
1. API Intro
Applicable object: Common mode Institutional mode
API rules:https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/receivers
Request method:POST
Path parameter is a path parameter.、
Query parameter needs to be passed in the request URL.
Body parameter needs to be passed in the request JSON.
2.Request Parameters
Name | Variable Name | Type | Required | Description |
---|---|---|---|---|
Sub-merchant ID | sub_mchid | string[1, 32] | No | body Sub-merchant ID allocated by WeChat Pay. It needs to be consistent with the sub-merchant ID in the transaction of WeChat Pay. |
Official account ID | appid | string[1, 32] | No | body Merchant official account ID allocated by WeChat. When the receiver type includes PERSONAL_OPENID, its filling is required. |
Sub-merchant official account ID | sub_appid | string[1, 32] | No | body Sub-merchant official account ID allocated by WeChat. When the receiver type includes PERSONAL_SUB_OPENID, its filling is required. |
Receiver type | type | string | Yes | body Receiver type. |
Receiver account | account | string[1, 64] | Yes | body When the type is MERCHANT_ID, it is a merchant ID |
Full name of receiver | name | string[1, 1024] | No | body Setup instructions:
a. When the receiver type is MERCHANT_ID, the full name of the merchant should be uploaded (required); |
Whether the user has given authorization to use their real-name information | authorized | boolean | No | body The merchant uploads the real-name and account information of the user to the WeChat Pay. The WeChat Pay backstage will assist in verifying the consistency of the user information to reduce the risk of filling mistakes of the receiver. This field indicates the authorization status of the user information to the merchant for confirmation and transmission:
Note: When the receiver type is PERSONAL_OPNEID/PERSONAL_SUB_OPENID and the account name (name field) is selected to be uploaded, its filling is required |
Relationship type with merchant | relation_type | string | Yes | body The relationship between the merchant and receiver. |
Custom funds-distribution relationship | custom_relation | string[1, 10] | No | body The specific relationship between merchant and receiver. This field contains a maximum of 10 characters. |
Detailed description of funds-distribution scenario | scene | string[3, 256] | Yes | body The merchant describes funds-distribution scenario in detail. |
Major service scope of receiver | major_service | string[3, 256] | No | body If the receiver type is MERCHANT_ID, its filling is required. Please provide the main service scenarios of the receiver, along with the public webpage link, mini program name, official account ID, and APPID (if applicable) for the funds-distribution scenarios. |
Expected funds-distribution ratio of receiver | expected_ratio | int | Yes | body Refers to the expected maximum funds-distribution ratio of the added receiver. This is only for information collection, but does not indicate the actual maximum funds-distribution ratio, which is subject to platform policy. |
The application letter document ID of the funds-distribution receiver has been added. | application_file_id | string[10, 128] | No | Body Please refer to the document submission method description at the beginning of the API. The document ID corresponding to the application letter of the funds-distribution receiver has been added. Please use the document uploading API to submit the document, and fill in this field after obtaining the document ID. |
the document ID of the cooperative relationship certificate between the funds-distribution initiator and receiver | partnership_file_id | string[10, 128] | No | Body Please refer to the document submission instructions at the beginning of the API for the document ID of the cooperative relationship certificate between the funds-distribution initiator and receiver This field is required if the receiver ID is MERCHANT_ID in the document ID of the cooperative relationship certificate between the funds-distribution initiator and receiver, (it is optional if V1.0 is used to combine documents for submission). Please use the document uploading API to submit the document, and fill in this field after obtaining the document ID. |
Request Example
Add merchant as a receiver
Add user as a receiver
3. Response Parameters
Name | Variable Name | Type | Required | Description |
---|---|---|---|---|
Sub-merchant ID | sub_mchid | string[1, 32] | No | Sub-merchant ID, same as the request parameter. |
Receiver type | type | string | Yes | Receiver type, same as the request parameter. |
Receiver account | account | string[1, 64] | Yes | Receiver account, same as the request parameter. |
Full name of receiver | name | string[1, 1024] | No | Full name of receiver, same as the request parameter. |
Relationship type with merchant | relation_type | string | Yes | Relationship type with merchant, same as the request parameter. |
Custom funds-distribution relationship | custom_relation | string[1, 10] | No | Customized funds-distribution relationship, same as the request parameter. |
Detailed description of funds-distribution scenario | scene | string[3, 256] | Yes | Detailed description of funds-distribution scenario, same as the request parameter. |
Major service scope of receiver | major_service | string[3, 256] | No | If the receiver type is MERCHANT_ID, its filling is required. Please provide the main service scenarios of the receiver, along with the public webpage link, mini program name, official account ID, and APPID (if applicable) for the funds-distribution scenarios. |
Expected funds-distribution ratio of receiver | expected_ratio | int | Yes | Expected funds-distribution ratio of receiver, same as the request parameter. |
Receiver relationship status | state | string | Yes | The relationship status between merchant and receiver. It is only allowed to distribute funds to the receiver in EFFECTIVE status. |
Receiver relationship add failure reason | fail_reason | string | No | The reason for failure to add receiver will only occur when state is AUDIT_FAILED |
Reason description for the failure to add receiver | fail_description | string[0, 2048] | No | The detailed description for the failure to add receiver will only appear when the state is AUDIT_FAILED. Please refer to the feedback and suggestions in the description, modify your request, and reattempt to add receiver. |
The application letter document ID of the funds-distribution receiver has been added. | application_file_id | string[10, 128] | 否 | BodyPlease refer to the document submission method description at the beginning of the API. The document ID corresponding to the application letter of the funds-distribution receiver has been added. Please use the document uploading API to submit the document, and fill in this field after obtaining the document ID. |
the document ID of the cooperative relationship certificate between the funds-distribution initiator and receiver | partnership_file_id | string[10, 128] | 否 | BodyPlease refer to the document submission instructions at the beginning of the API for the document ID of the cooperative relationship certificate between the funds-distribution initiator and receiver This field is required if the receiver ID is MERCHANT_ID in the document ID of the cooperative relationship certificate between the funds-distribution initiator and receiver, (it is optional if V1.0 is used to combine documents for submission). Please use the document uploading API to submit the document, and fill in this field after obtaining the document ID. |
Return Example
SUCCESS
ERROR
4. Error Code
Error Codes | Error Message | Description | Solution |
---|---|---|---|
400 | INVALID_REQUEST | The user type is PERSONAL_SUB_OPENID, the sub_appid in parameter is not set | The user type is PERSONAL_OPENID, please set appid field |
400 | INVALID_REQUEST | The user type is PERSONAL_SUB_OPENID, the sub_appid in parameter is not set | The user type is PERSONAL_SUB_OPENID, please set sub_appid field |
400 | INVALID_REQUEST | If the receiver type is MERCHANT_ID, set the merchant full name of the receiver in the name field | If the receiver type is MERCHANT_ID, set the merchant full name of the receiver in the name field |
400 | INVALID_REQUEST | If the receiver type is MERCHANT_ID, set the major service scope of receiver in the major_service field | If the receiver type is MERCHANT_ID, set the major service scope of receiver in the major_service field |
400 | INVALID_REQUEST | When the receiver relationship type is CUSTOM, set the custom_relation field | When the receiver relationship type is CUSTOM, set the custom_relation field |
400 | INVALID_REQUEST | Personal receiver selects to upload the name field but does not confirm authorized status of user | If the personal receiver selects to upload the name to verify the consistency with user's real-name information, the merchant needs to obtain the user authorization first and set the authorized field to true |
400 | INVALID_REQUEST | The real name information of the personal receiver on the WeChat side does not match the uploaded name field value | Confirm with the receiver their real-name information before executing the request |
400 | INVALID_REQUEST | A receiver relationship record has already existed and the expected maximum split ratio (expected_ratio) is not consistent with the request | Check whether the account and expected maximum distribution proportion are correctly filled in. If the receiver has been added, query the result through [Adding Receiver Result Query API] |
400 | INVALID_REQUEST | 已经存在一条分账接收方关系记录,且上传的双方合作关系合同文件ID字段(partnership_file_id)与本次请求不符 | Please check if the ID field (partnership_file_id) of the account and the cooperation contract between the two parties is filled in correctly. If the recipient has already been added, you can use 【 Query Recipient Add Result API 】 to query the result |
400 | INVALID_REQUEST | 已经存在一条分账接收方关系记录,且上传的分账接收方申请函文件ID字段(application_file_id)与本次请求不符 | Please check if the ID field (application_file_id) in the application letter for the account and sub ledger recipient is filled in correctly. If the recipient has already been added, you can use 【 Query Recipient Addition Results API】 to query the results |
403 | NO_AUTH | The merchant has not signed the overseas funds-distribution product | Refer to the product process and access preparation, confirm that the merchant has funds-distribution authorization, and initiate the request again |
403 | NO_AUTH | The merchant has enabled the funds-distribution product and is waiting for it to take effect (Usually takes effect the next day) | The funds-distribution function cannot be initiated on the first day. Please initiate the request on the next day |
403 | NO_AUTH | Receiver | Confirm that the receiver is legally compliant before requesting funds-distribution |
403 | NO_AUTH | The parent-child relationship of the merchant does not exist. Please use correct sub-merchant ID to initiate the request | Please check if the sub-merchant ID (sub_mchid) is filled in correctly |