Product Capability API Dictionary Interface Rules Access Specification FAQs Terms Update Log

Payments
- Quick Pay
- Native Payment
- JSAPI Payment
- In-App Payment
- Mini Program Payment
- H5 Payment
- Auto-Debit Payment
Funding Products
- Funds Distribution(Transaction)
- Funds Distribution(Operate)
- Funds Distribution(Refund)
- Funds Distribution(Bill and Fund)
Other Products
- Merchant Onboard
- H5 Payment Authorization Application
- Customs Declaration

Adding Receiver Result Query

Update Time：2025.01.07

After a merchant initiates a request to add a receiver, call the API to query the adding receiver result. Only when the receiver's documents are approved by the WeChat and the status of the receiver relationship is reversed to EFFECTIVE, the Funds-distribution Request API can be called to add the receiver.

1. API Intro

Applicable object： Common mode Institutional mode

API rules：https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/receivers/{account}

Request method：GET

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. Note: Only for Institutional 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 for Institutional 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

Request Example

URL

1https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/receivers/of8YZ6LPmjDmYAqdobIvwTdQQjR8?appid=wx8888888888888888&type=PERSONAL_OPENID

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

Return Example

SUCCESS

1{
2    "account":"of8YZ6LPmjDmYAqdobIvwTdQQjR8",
3    "custom_relation":"Authorized livestream salesperson",
4    "expected_ratio":800,
5    "relation_type":"CUSTOM",
6    "scene":"The receiver is the authorized livestream salesperson",
7    "state":"INIT",
8    "type":"PERSONAL_OPENID"
9}

ERROR

1{
2	"code": "SYSTEM_ERROR",
3	"message": "Parameter error"
4}

Error Code

Error Codes	Error Message	Description	Solution
404	NOT_FOUND	The receiver relationship does not exist	Check whether the receiver account, receiver type and other fields are filled in correctly
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	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