Weixin Pay Open Platform

Return Home / Cross-border Funds-Distribution / Adding Receiver API

Adding Receiver API

Latest update time：2022.05.18 Release notes

The 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.

Tips：

1. A funds-receiver relationship involves the funds-distribution initiator and receiver:
Where the funds-distribution initiator refers to [merchant] or [merchant and sub-merchant] (Direct-connected merchant ID in direct mode and parent merchant/sub-merchant IDs in the service provider/overseas institution mode);
The receiver refers to the personal WeChat account number or merchant ID that receives the distributed funds. The merchant needs to provide the receiver type and receiver account when adding receiver information;
For example, in the overseas institutional mode, there are two sub-merchants A1 and A2 under merchant A. B1 is the partner of A1 and B2 is the partner of A2;
—— In this case, in order to further distribute funds to sub-merchant B1 based on the funds-distribution to sub-merchant A1, the merchant A needs to add receivers: mchid:A + sub_mchid: A1 + account: B1;
——In order to further distribute funds to sub-merchant B2 based on the funds-distribution to sub-merchant A2, merchant A needs to add receivers: mchid:A + sub_mchid: A2 + account: B2;

2. Before initiating the request to add a receiver, the merchant needs to call the overseas file upload API to submit the attachments for WeChat to audit the receiver relationship. Prepare the following partnership documents in advance. If the materials are not fully uploaded, they may not be approved.
【Description of partnership documents】

a. Partnership contract between both parties:
When the receiver is a domestic enterprise, the electronic scan of the cooperation contract between the cross-border e-commerce and the receiver should be submitted (mandatory). When the receiver is a domestic individual, for each sub-merchant (of cross-border e-commerce), it is only necessary to provide a sample to prove the cooperation relationship between cross-border e-commerce and a domestic individual.

b. See Sub-merchant’s Application and Commitment for Adding Receivers for the template of .receiver application letter.

Note: Two documents can be submitted and used separately. the file upload API. After obtaining the file ID, fill in the [file_id] field.

a.Fill in the partnership_file_id field for the document ID corresponding to the "partnership contract" between the two parties.

b.Fill in the application_file_id field for the document ID corresponding to the "application letter for funds-distribution recipient".

Check formula: The maximum amount of each order that can be allocated to other parties = Payment amount of the original order * Maximum allocation proportion (currently the maximum allocation proportion is adjusted and controlled by the platform; refer to the product overview page).

3. After the API is called successfully, the receiver relationship status is INIT. After the receiver's documents are approved by WeChat and the status of the receiver relationship is reversed to EFFECTIVE, the Funds-distribution Request API can be called to add receiver. Call Adding Receiver Result Query API to confirm whether the receiver relationship has taken effect (approved).

4. If the receiver relationship fails in the audit, re-submit the complete and conforming documents through the file upload API according to the reason for failure prompt field and re-initiate the request to add receiver Note: Initiating a request to add receiver in INIT/EFFECTIVE status is not allowed.

API Intro

Request Url:https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/receivers

Request method:POST

API rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3

Applicable object:Common modeInstitutional mode

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.

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. Note: Only forInstitutional mode Example:1900000109
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. Example:wx8888888888888888
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. Note: Only forInstitutional mode Example:wx8888888888888889
Receiver type	type	string	Yes	body Receiver type. MERCHANT_ID: Merchant ID, PERSONAL_OPENID: Personal OpenID, converted by merchant APPID PERSONAL_SUB_OPENID: Personal Sub_OpenID, converted by sub-merchant APPID Example:MERCHANT_ID
Receiver account	account	string[1, 64]	Yes	body When the type is MERCHANT_ID, it is a merchant ID When the type is PERSONAL_OPENID, it is a personal OpenID When the type is PERSONAL_SUB_OPENID, it is a personal Sub_OpenID Example:86693852
Full name of receiver	name	string[1, 1024]	No	body Setup instructions: 1. Note: This field needs to be encrypted. See the description of sensitive information encryption at the beginning of the document for encryption method. 2. The setting rules are as follows based on different receiver types: a. When the receiver type is MERCHANT_ID, the full name of the merchant should be uploaded (required); b. When the receiver type is PERSONAL_OPENID or PERSONAL_SUB_OPENID, the personal name can be uploaded (optional. If it is uploaded, verify whether the field value is consistent with the real-name information on the WeChat Pay side, and the authorized field needs to be set to confirm whether the user information is authorized.) Example:Merchant name
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: 1) false indicates that the user information is not authorized and WeChat Pay will refuse to receive data 2) true indicates that the user information has been authorized and WeChat Pay will normally receive data 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 Example:true
Relationship type with merchant	relation_type	string	Yes	body The relationship between the merchant and receiver. SUPPLIER: Supplier, DISTRIBUTOR: Distributor, TAX_SERVICE_PROVIDER: Tax service provider, IT_SERVICE_PROVIDER: Technical service provider, CUSTOM: Custom, Example:SERVICE_PROVIDER
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. When the relation_type is CUSTOM, it is a required field When the relation_type is not CUSTOM, it is not a required field Example:agent
Detailed description of funds-distribution scenario	scene	string[3, 256]	Yes	body The merchant describes funds-distribution scenario in detail. Example:The receiver is the domestic tax service provider, which helps the merchant withhold and pay the tax to the domestic customs.
Major service scope of receiver	major_service	string[3, 256]	No	body Describe major service scope of the company When the destination type is MERCHANT_ID, it is a required field. Example:Tax preparation service
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. Unit: per ten thousand. For example, 2000 indicates 20%. Example:2000
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. Example：439d2325-f878-8960-8719-604ed42f1139
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. Example：de851a06-5a38-9d31-a102-275a17c477de

Request Sample

Example：

{
     "account": "1900000109",
    "expected_ratio": 1000,
    "partnership_file_id":"83f5c0f9-7c0d-4b3b-9136-ef16fd9cb644",
    "application_file_id":"3a00187-426c-4815-8ea7-b0d1ef46647b",
    "major_service": "Tax preparation service",
    "name": "tdcUez3ov/jAzO2sDwLap6uc8d2itP6ffhoQzOa9LDzrMOqz/+reA79+e3aijKn0dQ2tPA391byJY6VqSaPhCpDJgvoawBYCNxkPR+ID9SYq/axfI4hN66aO/d8PWcKyEV/4AuVJEJ3ZIhvJXfnkoxmP6vF3yv7g1zS/IL1dTHCqY4X2tTpko4BRylcfz2Fi82CLbSegaB1h3SOsmstiC/wf2MM5rSnamgTAKA0a7w5+0QsvmNWbU9pVkOnHCGTGLUQFpDMpDvMtJS/f8vrrCPAeJa6ijwF7WLOqTV3cVWFYAtSC3iSDGyD7p2axHqsrirJo8fq63lYSRrTia1vgnA==",
    "relation_type": "TAX_SERVICE_PROVIDER",
    "scene": "The receiver is the domestic tax service provider, which helps the merchant withhold and pay the tax to the domestic customs.",
    "sub_mchid": "999968480",
    "type": "MERCHANT_ID"
  }

{
    {
    "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8", 
    "appid": "wx78898sdfwe9888835", 
    "relation_type": "CUSTOM", 
    "custom_relation": "agent", 
    "expected_ratio": 800, 
    "scene": "The receiver is the domestic tax service provider, which helps the merchant withhold and pay the tax to the domestic customs.", 
    "name": "tdcUez3ov/jAzO2sDwLap6uc8d2itP6ffhoQzOa9LDzrMOqz/+reA79+e3aijKn0dQ2tPA391byJY6VqSaPhCpDJgvoawBYCNxkPR+ID9SYq/axfI4hN66aO/d8PWcKyEV/4AuVJEJ3ZIhvJXfnkoxmP6vF3yv7g1zS/IL1dTHCqY4X2tTpko4BRylcfz2Fi82CLbSegaB1h3SOsmstiC/wf2MM5rSnamgTAKA0a7w5+0QsvmNWbU9pVkOnHCGTGLUQFpDMpDvMtJS/f8vrrCPAeJa6ijwF7WLOqTV3cVWFYAtSC3iSDGyD7p2axHqsrirJo8fq63lYSRrTia1vgnA==",
    "authorized":true,
    "sub_mchid": "999968480",
    "type": "PERSONAL_OPENID",
    "partnership_file_id":"83f5c0f9-7c0d-4b3b-9136-ef16fd9cb644",
    "application_file_id":"3a00187-426c-4815-8ea7-b0d1ef46647b"
}

Return Parameters

Name	Variable Name	Type	Required	Description
Sub-merchant ID	sub_mchid	string[1, 32]	No	Sub-merchant ID, same as the request parameter. Note: Only forInstitutional mode Example:1900000109
Receiver type	type	string	Yes	Receiver type, same as the request parameter. MERCHANT_ID: Merchant ID, PERSONAL_OPENID: Personal OpenID, converted by merchant APPID PERSONAL_SUB_OPENID: Personal Sub_OpenID, converted by sub-merchant APPID Example:MERCHANT_ID
Receiver account	account	string[1, 64]	Yes	Receiver account, same as the request parameter. Example:86693852
Full name of receiver	name	string[1, 1024]	No	Full name of receiver, same as the request parameter. Example:hu89ohu89ohu89o
Relationship type with merchant	relation_type	string	Yes	Relationship type with merchant, same as the request parameter. SUPPLIER: Supplier, DISTRIBUTOR: Distributor, TAX_SERVICE_PROVIDER: Tax service provider, IT_SERVICE_PROVIDER: Technical service provider, CUSTOM: Custom, Example:SUPPLIER
Custom funds-distribution relationship	custom_relation	string[1, 10]	No	Customized funds-distribution relationship, same as the request parameter. Example:agent
Detailed description of funds-distribution scenario	scene	string[3, 256]	Yes	Detailed description of funds-distribution scenario, same as the request parameter. Example:The receiver is the domestic tax service provider, which helps the merchant withhold and pay the tax to the domestic customs.
Major service scope of receiver	major_service	string[3, 256]	No	Major service scope of receiver, same as the request parameter. Example:Tax preparation service
Expected funds-distribution ratio of receiver	expected_ratio	int	Yes	Expected funds-distribution ratio of receiver, same as the request parameter. Example:2000
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. INIT: The receiver information is to be audited by WeChat EFFECTIVE: The receiver relationship is in effect AUDIT_FAILED: The receiver relationship failed in the audit Example:AUDIT_FAILED
Receiver relationship add failure reason	fail_reason	string	No	The reason for failure to add receiver will only occur when state is AUDIT_FAILED PARTNERSHIP_NOT_SUPPORTED: The partnership relationship with the receiver does not support Funds-distribution. DEFAULT_ERROR: Default error, Example:PARTNERSHIP_NOT_SUPPORTED
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. Example：439d2325-f878-8960-8719-604ed42f1139
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. Example：de851a06-5a38-9d31-a102-275a17c477de

Return Example


{
    "account":"of8YZ6LPmjDmYAqdobIvwTdQQjR8",
    "custom_relation":"agent",
    "expected_ratio":800,
    "relation_type":"CUSTOM",
    "scene":"The receiver is the domestic tax service provider, which helps the merchant withhold and pay the tax to the domestic customs.",
    "state":"EFFECTIVE",
    "sub_mchid": "999968480",
    "type":"PERSONAL_OPENID",
    "partnership_file_id":"83f5c0f9-7c0d-4b3b-9136-ef16fd9cb644",
    "application_file_id":"3a00187-426c-4815-8ea7-b0d1ef46647b"
}

{
"code":"SYSTEM_ERROR",
"message":"Parameter error"
}

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
	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
	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
	INVALID_REQUEST	If the receiver type is MERCHANT_ID, set the major service scope of receiver in the major_service field	Check receiver list and remove duplicate IDs in the same request before requesting funds-distribution
	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
	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
	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
	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[query distribution receiver add result API]
	INVALID_REQUEST	A receiver relationship record has already existed and the uploaded file id field (file_id) to be audited is not consistent with the request	Check whether the account and the file ID field (file_id) are filled in correctly. If the receiver has been added, query the result through[query Sub Ledger receiver add result API]
	INVALID_REQUEST	The binding relationship between the AppID passed in and the initiating merchant does not exist.	Please confirm whether the appid field and the initiator merchant are successfully bound.
	INVALID_REQUEST	The binding relationship between the SubAppID passed in and the corresponding sub-merchant does not exist.	Confirm whether the sub_appid field and the sub-merchant are successfully bound. The institution can view the sub_appid field bound by the sub-merchant by selecting Merchant Platform > Institution > Application > Development configuration.
	INVALID_REQUEST	Please refer to the platform guidelines when submitting the documents for funds-distribution partnership.	Please refer to the platform guidelines when submitting the documents for funds-distribution partnership.
	INVALID_REQUEST	Please refer to the platform guidelines when submitting the "application letter for funds-distribution recipient" in the funds-distribution partnership information.	Please refer to the platform guidelines when submitting the "application letter for funds-distribution recipient" in the funds-distribution partnership information.
	USER_ERROR	The recipient has not completed the real name verification.	The corresponding user has not completed the real name verification at the time the user recipient is added. Please advise user to complete the real name verification first, otherwise the user's WeChat balance account will not be able to accept payment requests.
	INVALID_REQUEST	A funds-distribution recipient relationship record already exists and the ID field (partnership_file_id) of the uploaded "partnership contract" between the two parties is not consistent with the request.	Check whether the account and the ID field (partnership_file_id) of the partnership contract between the two parties are filled in correctly. If the recipient has been added, query the result through [Add-Recipient Result Query API].
	INVALID_REQUEST	A funds-distribution recipient relationship record already exists and the ID field (application_file_id) of the uploaded "application letter for funds-distribution recipient" is not consistent with the request.	Check whether the account and the ID field (application_file_id) of the "application letter for funds-distribution recipient" are filled in correctly. If the recipient has been added, query the result through [Add-Recipient Result Query API]
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

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Cross-border Funds-Distribution API

Adding Receiver API

Tips：

API Intro

Request Parameters

Request Sample

Example：

Return Parameters

Return Example

Error Code

Release notes