Request funds-distribution

Update Time：2025.01.07

After the Weixin transaction is successfully completed, the merchant initiates a funds-distribution request and distributes the settled funds to the receiver.

Tips：

The funds-distribution requests for the same transaction can be initiated up to 50 times and the funds can be distributed to a maximum of 50 parties each request;

The API is in asynchronous processing mode, that is, after receiving the merchant's request, it will be accepted first and then processed asynchronously, and the final funds-distribution result can be obtained through the funds-distribution Result Query API;

API supports the merchant to initiate funds-distribution multiple times for the same transaction. See the description of the unfreeze_unsplit field in the request parameters for details (refer to the supplementary call example after the documents);

The unfrozen funds for the sponsor outbound through the API, together with the non-funds-distribution transaction amount, is subject to the net settlement. The regulations are consistent with the settlement period, starting point and other withdrawal rules in the settlement contract with the merchant;

The sponsor refers to the merchant who has actually settled the funds and entered the funds into the account via Weixin Pay. It refers to a merchant in the overseas institution mode, and a sub-merchant in the service provider mode.

Merchants use the public key of Weixin Pay for encryption when uploading sensitive information. The certificate serial number is included in Weixinpay-Serial in the HTTP header of the request. See API Rules for details.

1. API Intro

Applicable object： Common mode Institutional mode

API rules：https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/orders

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]

Body Sub-merchant ID allocated by Weixin Pay. It needs to be consistent with the sub-merchant ID in the transaction of Weixin Pay.
Note: Only for Institutional mode
Example: 1900000109

Official account ID

appid

string[1, 32]

Body Merchant official account ID allocated by Weixin. When the receiver type includes PERSONAL_OPENID, its filling is required.
Example: wx8888888888888888

Sub-merchant official account ID

sub_appid

string[1, 32]

Body Sub-merchant official account ID allocated by Weixin. When the receiver type includes PERSONAL_SUB_OPENID, its filling is required.
Note: Only for Institutional mode
Example: wx8888888888888889

Weixin Pay transaction ID

transaction_id

string[1, 32]

Yes

Body Weixin Pay transaction ID
Example: 4208450740201411110007820472

Merchant order No.

out_order_no

string[1, 64]

Yes

Body The order No. in the merchant system, which is unique. It can only include numbers, capital letters and lowercase letters _-.
Note: This order No. is used to identify different requests of funds-distribution commands (including funds-distribution request API/unfreezing remaining funds API) initiated from the merchant side.
If the funds of one transaction is distributed multiple times, change the [merchant order No.] before requesting funds-distribution. Otherwise it will be considered as a repeated request.
Example: P20150806125346

Whether to unfreeze the remaining undistributed funds

unfreeze_unsplit

boolean

Yes

Body 1. If true, the remaining undistributed funds amount of the transaction will be unfrozen to the sponsor's account outbound;

If false, the remaining undistributed funds amount of the transaction will not be unfrozen to the sponsor's account and the transaction funds can be distributed again.

Example: true

Receiver list

receivers

array[1，50]

Body Receiver list. If unfreeze_unsplit=false, the sponsor can be set as the receiver. Otherwise, the funds-distribution request will be rejected. There can be up to 50 receivers.

Receiver list

Name	Variable Name	Type	Required	Description
Distribution currency	currency	string[3, 3]	Yes	Distribution currency, a three-letter code that meets the requirements of ISO 4217 standard. Currently only support "CNY". Example: CNY
Receiver type	type	string[1, 32]	Yes	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	When the type is MERCHANT_ID, it is the merchant ID When the type is PERSONAL_OPENID, it is the personal OpenID When the type is PERSONAL_SUB_OPENID, it is the personal Sub_OpenID. Note: Currently, the personal OpenID cannot be added as a receiver Example: 86693852
Funds-distribution personal receiver name	name	string[1, 1024]	No	Optional, when the receiver type is personal. If filled in, check whether the name is consistent with the real-name of the Weixin user. If the name is inconsistent, the funds-distribution request will be rejected When the receiver type is PERSONAL_OPENID or PERSONAL_SUB_OPENID, the ciphertext of the personal name can be filled in (Optional. Check it When you fill it in). This field needs to be encrypted. See the description of sensitive information encryption at the beginning of the document for the encryption method. Example: hu89ohu89ohu89o
Whether the user has given authorization to use their real-name information	authorized	boolean	No	The merchant uploads the real-name and account information of the user to Weixin Pay. The Weixin Pay backstage will assist in verifying the consistency of the user information to reduce the risk of mistakes of the receiver. This field indicates the authorization status of the user information to the merchant for confirmation and transmission: False indicates that the user information is not authorized and Weixin Pay will refuse to receive data True indicates that the user information has been authorized and Weixin Pay will receive data Note: When the personal receiver name field is set, it is a required field Example: true
Funds-distribution amount	amount	int	Yes	Funds-distribution amount, unit: cents;Can only be an integer and cannot exceed the payment amount of the original transaction; In addition, in the scenario of funds-distribution to other receivers, verify whether the distributed funds amount exceeds the maximum funds-distribution proportion amount. Example: 888
Funds-distribution description	description	string[1, 80]	Yes	Reason description of Funds-distribution, to be reflected in the funds-distribution record Example: Distribute to merchant A

Request Example

Scenario 1

The merchant only needs to call the funds-distribution API once to complete the distribution of transaction funds
The transaction funds amount is CNY10. After deducting the service charge, the remaining amount to be distributed is CNY9.95. In this case, the merchant can initiate the funds-distribution request through [Funds-distribution Request API].
a. Assigned to distribute CNY0.99 to the cooperative merchant (2480248971)
b. Distribute CNY0.99 to the cooperative user (of8YZ9LPmjDmYAddobIvtTdQQjR8)
c. Set unfreeze_unsplit to true and unfreeze the remaining funds to the sponsor outbound. The funds-distribution of the transaction is completed.

Scenario 1：JSON

1{
2    "appid": "wx7bc98d929da735fe",
3    "out_order_no": "MCH13SFDG234155321146",
4    "receivers": [
5      {
6        "account": "2480248971",
7        "amount": 99,
8        "currency": "CNY",
9        "description": "distribute to xxx merchant-10%",
10        "type": "MERCHANT_ID"
11      },
12      {
13        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
14        "amount": 99,
15        "currency": "CNY",
16        "description": "distribute to xxx user-10%",
17        "type": "PERSONAL_OPENID"
18      }
19    ],
20    "sub_mchid": "999968479",
21    "transaction_id": "4200000012202203235765130087",
22    "unfreeze_unsplit": true
23}

Scenario 2

The merchant splits the same transaction multiple times for funds-distribution according to its own needs.
The transaction funds amount is CNY200. After deducting the service charge, the remaining amount to be distributed is CNY199. The merchant intends to distribute 50% of the funds (CNY100). In this case, the merchant can initiate the funds-distribution request through [Funds-distribution Request API].
a. Assigned to distribute CNY10 to the cooperative merchant (2480248971);
b. Distribute CNY10 to the cooperative user (of8YZ6LPmjDmYAqdobIvwTdQQjR8);
c. Set unfreeze_unsplit to false (if the remaining amount is frozen, it indicates that the funds-distribution is required subsequently). Specify the sponsor as the receiver and unfreeze CNY80 back to the receiver account to participate in the net settlement of the day.

Scenario 2：JSON

1{
2    "appid": "wx7bc98d929da735fe",
3    "out_order_no": "MCH1349FG041421146",
4    "receivers": [
5      {
6        "account": "2480248971",
7        "amount": 1000,
8        "currency": "CNY",
9        "description": "order 1: distribute to xxx merchant",
10        "type": "MERCHANT_ID"
11      },
12      {
13        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
14        "amount": 1000,
15        "currency": "CNY",
16        "description": "order 1: distribute to xxx user",
17        "type": "PERSONAL_OPENID"
18      },
19      {
20        "account": "999952224", # Note: fill in the sponsor merchant ID here
21        "amount": 8000,
22        "currency": "CNY",
23        "description": "order 1: unfreeze funds outbound",
24        "type": "MERCHANT_ID"
25      }
26    ],
27    "sub_mchid": "999968479",
28    "transaction_id": "4200000028202203236604547485",
29    "unfreeze_unsplit": false
30}

3. Response Parameters

Name

Variable Name

Type

Required

Description

Sub-merchant ID

sub_mchid

string[1, 32]

Merchant ID allocated by Weixin Pay
Note: Only for Institutional mode
Example: 1900000109

Weixin Pay order No.

transaction_id

string[1, 32]

Yes

Weixin Pay transaction ID
Example: 4208450740201411110007820472

Merchant order No.

out_order_no

string[1, 64]

Yes

Merchant order No., same as the request parameter.
Example: P20150806125346

Weixin order ID

order_id

string[1, 64]

Yes

Weixin order ID, the unique identifier returned by Weixin system.
Example: 3008450740201411110007820472

Funds-distribution order state

state

string

Yes

Funds-distribution order state (see result field in receivers for funds-distribution results of each receiver).
PROCESSING: Funds-distribution is processing,
FINISHED: Funds-distribution is finished,
Example: FINISHED

Receiver list

receivers

array[1,50]

Yes

Receiver list
When a merchant initiates a funds-distribution request or a unfreeze the remaining funds request, the same transaction funds can be distributed to multiple receivers (including unfreezing funds to the sponsor). The funds-distribution detail describes each funds-distribution state of each receiver.

Receiver list

Name	Variable Name	Type	Required	Description
Distribution currency	currency	string[3, 3]	Yes	Distribution currency, same as the request parameter. Example: CNY
Funds-distribution amount	amount	int	Yes	Funds-distribution amount, same as the request parameter. Example: 100
Funds-distribution description	description	string[1, 80]	Yes	Merchant order No., same as the request parameter. Example: Distribute to merchant 1900000110
Receiver type	type	string[1, 32]	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: 1900000109
The result of each funds-distribution detail.	result	string[1, 32]	Yes	The result of each funds-distribution detail. PENDING: Funds to be distributed, SUCCESS: Funds-distribution succeeded, CLOSED: Funds-distribution closed, Example: SUCCESS
Funds-distribution detail fail reason	fail_reason	string[1, 64]	No	Funds-distribution detail fail reasons. Set only when funds-distribution detail result is "CLOSED." NO_RELATION: The funds-distribution relationship has been terminated. SUB_MERCHANT_FRONEN: The sub-merchant account is frozen, MCH_CONTRACT_SETTLE_OFF: The merchant settlement contract is in closed state. MCH_CONTRACT_FROZEN: The merchant settlement contract is frozen, ACCOUNT_ABNORMAL: The receiver account is abnormal, RECEIVER_HIGH_RISK: The receiver is at high risk, RECEIVER_REAL_NAME_NOT_VERIFIED: The receiver has not been real-name verified, NO_AUTH: The funds-distribution authorization has been canceled, DEFAULT_ERROR: Default error, Example: ACCOUNT_ABNORMAL
Funds-distribution detail creation time	create_time	string[1, 64]	Yes	Funds-distribution detail creation time follows RFC3339 standard format Example: 2015-05-20T13:29:35.120+08:00
Funds-distribution detail finish time	finish_time	string[1, 64]	No	Funds-distribution detail finish time follows RFC3339 standard format. Set only when the funds-distribution detail result is "SUCCESS" or "CLOSED". Example: 2015-05-20T13:29:35.120+08:00
Weixin funds-distribution detail ID	detail_id	string[1, 64]	Yes	Weixin funds-distribution detail ID is the details ID of each funds-distribution business. Example: 36011111111111111111111
Receiver type	detail_type	string[1, 32]	Yes	The funds-distribution details include two categories of funds: Funds distributed to other receivers and funds unfrozen to sponsor. These two categories can be distinguished by the field. If the detail type is UNFREEZE_TO_SPONSOR, the funds-distribution details will indicate settlement currency, settlement amount and exchange rate and other information. DISTRIBUTE_TO_OTHERS: Distribute funds to other receivers, UNFREEZE_TO_SPONSOR: Unfreeze funds to the sponsor outbound, Example: DISTRIBUTE_TO_OTHERS
Settlement currency	settlement_currency	string[3, 3]	No	The field is set only when the detail type is UNFREEZE_TO_SPONSOR. Example: HKD
Settled amount	settlement_amount	int	No	The funds amount is finally settled via exchange rate to the sponsor, using the minimum currency unit. Example: 110
Exchange rate value	rate	int	No	The value is the exchange ratio between the distribution currency and the settlement currency multiplied by the 8th power of 10. If the distribution currency and settlement currency are both CNY, the exchange ratio is 1 and the exchange rate value is 100,000,000; If the settlement currency is USD, assuming that the ratio of USD to CNY is 6.5, the exchange rate value is 650,000,000. Example: 81000000

Return Example

Scenario 1

1{
2    "order_id": "7100000751202203238026613597498",
3    "out_order_no": "MCH13SFDG234155321146",
4    "receivers": [
5      {
6        "account": "999952224", # Note: The account is the sponsor merchant ID
7        "amount": 797,
8        "create_time": "2022-03-23T17:10:13+08:00",
9        "currency": "CNY",
10        "description": "Unfreeze the remaining funds to sponsor",
11        "detail_id": "7200000751202203238026613597602",
12        "detail_type": "UNFREEZE_TO_SPONSOR",
13        "rate_value": 83640300,
14        "result": "PENDING",
15        "settlement_amount": 952,
16        "settlement_currency": "HKD",
17        "type": "MERCHANT_ID"
18      },
19      {
20        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
21        "amount": 99,
22        "create_time": "2022-03-23T17:10:13+08:00",
23        "currency": "CNY",
24        "description": "Distribute to xxx user-10%",
25        "detail_id": "7200000751202203238026613597699",
26        "detail_type": "DISTRIBUTE_TO_OTHERS",
27        "result": "PENDING",
28        "type": "PERSONAL_OPENID"
29      },
30      {
31        "account": "2480248971",
32        "amount": 99,
33        "create_time": "2022-03-23T17:10:13+08:00",
34        "currency": "CNY",
35        "description": "Distribute to xxx merchant-10%",
36        "detail_id": "7200000751202203238026613597767",
37        "detail_type": "DISTRIBUTE_TO_OTHERS",
38        "result": "PENDING",
39        "type": "MERCHANT_ID"
40      }
41    ],
42    "state": "PROCESSING",
43    "sub_mchid": "999968479",
44    "transaction_id": "4200000012202203235765130087"
45}

Scenario 2

1{
2    "order_id": "7100000749202203238028118660977",
3    "out_order_no": "MCH1349FG041421146",
4    "receivers": [
5      {
6        "account": "999952224",
7        "amount": 8000,
8        "create_time": "2022-03-23T17:35:18+08:00",
9        "currency": "CNY",
10        "description": "order 1: unfreeze funds outbound",
11        "detail_id": "7200000749202203238028118661068",
12        "detail_type": "UNFREEZE_TO_SPONSOR",
13        "rate_value": 83640300,
14        "result": "PENDING",
15        "settlement_amount": 9564,
16        "settlement_currency": "HKD",
17        "type": "MERCHANT_ID"
18      },
19      {
20        "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
21        "amount": 1000,
22        "create_time": "2022-03-23T17:35:18+08:00",
23        "currency": "CNY",
24        "description": "order 1: distribute to xxx user",
25        "detail_id": "7200000749202203238028118661146",
26        "detail_type": "DISTRIBUTE_TO_OTHERS",
27        "result": "PENDING",
28        "type": "PERSONAL_OPENID"
29      },
30      {
31        "account": "2480248971",
32        "amount": 1000,
33        "create_time": "2022-03-23T17:35:18+08:00",
34        "currency": "CNY",
35        "description": "order 1: distribute to xxx merchant",
36        "detail_id": "7200000749202203238028118661205",
37        "detail_type": "DISTRIBUTE_TO_OTHERS",
38        "result": "PENDING",
39        "type": "MERCHANT_ID"
40      }
41    ],
42    "state": "PROCESSING",
43    "sub_mchid": "999968479",
44    "transaction_id": "4200000028202203236604547485"
45}

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	The user OpenID and the uploaded AppID do not match	Verify under which merchant authorization scenario the OpenID is obtained and set the related AppID field by referring to the description of the receiver type field in the APIs document
400	INVALID_REQUEST	Duplicate IDs in the receiver list when requesting funds-distribution	Check receiver list and remove duplicate IDs in the same request before requesting funds-distribution
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 Weixin does not match the uploaded name field value when requesting funds-distribution	Confirm with the receiver their real-name information before executing the request
400	INVALID_REQUEST	Currently, only CNY is supported in funds-distribution	Check receiver list and adjust the distribution currency to CNY before requesting funds-distribution
400	INVALID_REQUEST	The transaction has exceeded the maximum time limit for funds-distribution	Re-check the payment time of the transaction. Transactions exceeding the maximum time limit for are not allowed to initiate funds-distribution. (the system has initiated unfreezing the funds for settlement outbound)
400	INVALID_REQUEST	The transaction does not support funds-distribution	Check whether the Weixin Pay transaction ID is filled in incorrectly and confirm that the Funds-distribution Mark API is called successfully before calling the transaction API
400	INVALID_REQUEST	The merchant information in the request of funds-distribution is inconsistent with that in the original transaction	Carefully check whether the transaction ID is filled in correctly and whether the sub-merchant has been filled in or filled in incorrectly
400	INVALID_REQUEST	If you choose to unfreeze the remaining undistributed funds amount, that is, set unfreeze_unsplit to true in the funds-distribution request, you cannot add the sponsor as the receiver	If you choose to unfreeze the remaining funds amount to be distributed, that is, set unfreeze_unsplit to true in the funds-distribution request, remove the sponsor account from the receiver list before requesting funds-distribution
400	INVALID_REQUEST	When partial unfreezing is selected, the account for the unfrozen funds is filled in incorrectly. (Should be set as the actual sponsor)	Set the sponsor as the actual settled funds Weixin account. Fill in merchant ID for the institution and sub-merchant ID for the service provider
400	INVALID_REQUEST	When requesting funds-distribution and it has been verified that the funds receiver relationship does not exist. Check whether all receivers have been added	Check whether all receivers have been added
400	INVALID_REQUEST	When requesting funds-distribution and it has been verified that the funds receiver relationship is not in effect or has been terminated. Check whether all receivers are in effect	Check whether all receivers are in effect
403	USER_ERROR	There is a receiver that has not been real-name verified in the receiver list, and their Weixin balance account cannot accept the payment request	Check receiver list and confirm that the receiver user has been real-name verified before requesting funds-distribution
403	USER_ERROR	There is a receiver whose account is restricted for collection in the receiver list, and their cumulative collection amount in the balance + current collection amount has exceeded the limit	In the case of exceeding the collection amount limit, the restricted user will receive Weixin's push message. Please guide the question receiver to complete the upgrade according to the guidelines before requesting funds-distribution
403	USER_ERROR	There is a receiver whose account has hit the Weixin risk interception strategy in the receiver list, and their account is restricted from collection	The user's account intercepted with risk prompts from the platform side is subject to full-scenario collection restriction. Please eliminate the related risky receiver before requesting funds-distribution
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
400	INVALID_REQUEST	The command (out_order_no) already exists when the merchant requests funds-distribution and the receiver is inconsistent with that in the existing funds-distribution command	In case of the same funds-distribution request, check whether the receiver information is consistent. In case of different funds-distribution requests, change the command (out_order_no) before requesting funds-distribution
400	INVALID_REQUEST	The command (out_order_no) already exists when the merchant requests funds-distribution and the funds-distribution amount is inconsistent with that in the existing funds-distribution command	In case of the same funds-distribution request, check whether the funds-distribution amount is consistent. In case of different funds-distribution requests, change the command (out_order_no) before requesting funds-distribution
400	INVALID_REQUEST	The command (out_order_no) already exists when the merchant requests funds-distribution and the funds amount detail is inconsistent with that in the existing funds-distribution command	In case of the same funds-distribution request, check whether the receiver list is consistent. In case of different funds-distribution requests, change the command (out_order_no) before requesting funds-distribution
400	INVALID_REQUEST	The command (out_order_no) already exists when the merchant unfreezes the remaining funds and the details are not as expected	In case of different funds-distribution requests, change the command (out_order_no) before requesting funds-distribution
400	INVALID_REQUEST	Funds settlement outbound amount cannot be 0 when requesting to unfreeze the distributed funds outbound	Adjust the unfreezing funds amount (CNY) appropriately so that the amount of foreign currency after conversion into foreign currency is greater than 0
400	INVALID_REQUEST	The split funds amount exceeds the maximum split percentage when requesting funds-distribution	Adjust the split funds amount to be within the split ratio limit before requesting funds-distribution
400	INVALID_REQUEST	The number of funds-distribution of the transaction has exceeded the maximum funds-distribution times, funds-distribution cannot be initiated.	Call [Unfreeze Remaining Amount API] to unfreeze funds
403	NOT_ENOUGH	The funds amount to be distributed is insufficient at the time of request	The current remaining funds amount to be distributed can be obtained through [Remaining Funds Amount to be Distributed Query API]
500	SYSYTEM_ERROR	The freeze process of the transaction funds specified by the merchant when initiating funds-distribution request has not been completed. Try again later	After the user completes the payment, the fund freezing process for the transaction with funds-distribution will be triggered. It is recommended that the merchant try again after 3~5 mins