Latest update time:2022.05.18 Release notes
After the Weixin transaction is successfully completed, the merchant initiates a funds-distribution request and distributes the settled funds to the receiver.
● 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.
Request Url:https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/orders
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.
Name | Variable Name | Type | Required | Description |
---|---|---|---|---|
Sub-merchant ID | sub_mchid | string[1, 32] | No | 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 forInstitutional mode Example:1900000109 |
Official account ID | appid | string[1, 32] | No | 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] | No | body Sub-merchant official account ID allocated by Weixin. When the receiver type includes PERSONAL_SUB_OPENID, its filling is required. Note: Only forInstitutional 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; 2. 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] | No | bodyReceiver 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. |
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.
{
"appid": "wx7bc98d929da735fe",
"out_order_no": "MCH13SFDG234155321146",
"receivers": [
{
"account": "2480248971",
"amount": 99,
"currency": "CNY",
"description": "distribute to xxx merchant-10%",
"type": "MERCHANT_ID"
},
{
"account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
"amount": 99,
"currency": "CNY",
"description": "distribute to xxx user-10%",
"type": "PERSONAL_OPENID"
}
],
"sub_mchid": "999968479",
"transaction_id": "4200000012202203235765130087",
"unfreeze_unsplit": true
}
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.
{
"appid": "wx7bc98d929da735fe",
"out_order_no": "MCH1349FG041421146",
"receivers": [
{
"account": "2480248971",
"amount": 1000,
"currency": "CNY",
"description": "order 1: distribute to xxx merchant",
"type": "MERCHANT_ID"
},
{
"account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
"amount": 1000,
"currency": "CNY",
"description": "order 1: distribute to xxx user",
"type": "PERSONAL_OPENID"
},
{
"account": "999952224", # Note: fill in the sponsor merchant ID here
"amount": 8000,
"currency": "CNY",
"description": "order 1: unfreeze funds outbound",
"type": "MERCHANT_ID"
}
],
"sub_mchid": "999968479",
"transaction_id": "4200000028202203236604547485",
"unfreeze_unsplit": false
}
Name | Variable Name | Type | Required | Description |
---|---|---|---|---|
Sub-merchant ID | sub_mchid | string[1, 32] | No | Merchant ID allocated by Weixin Pay Note: Only forInstitutional 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. |
{
"order_id": "7100000751202203238026613597498",
"out_order_no": "MCH13SFDG234155321146",
"receivers": [
{
"account": "999952224", # Note: The account is the sponsor merchant ID
"amount": 797,
"create_time": "2022-03-23T17:10:13+08:00",
"currency": "CNY",
"description": "Unfreeze the remaining funds to sponsor",
"detail_id": "7200000751202203238026613597602",
"detail_type": "UNFREEZE_TO_SPONSOR",
"rate_value": 83640300,
"result": "PENDING",
"settlement_amount": 952,
"settlement_currency": "HKD",
"type": "MERCHANT_ID"
},
{
"account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
"amount": 99,
"create_time": "2022-03-23T17:10:13+08:00",
"currency": "CNY",
"description": "Distribute to xxx user-10%",
"detail_id": "7200000751202203238026613597699",
"detail_type": "DISTRIBUTE_TO_OTHERS",
"result": "PENDING",
"type": "PERSONAL_OPENID"
},
{
"account": "2480248971",
"amount": 99,
"create_time": "2022-03-23T17:10:13+08:00",
"currency": "CNY",
"description": "Distribute to xxx merchant-10%",
"detail_id": "7200000751202203238026613597767",
"detail_type": "DISTRIBUTE_TO_OTHERS",
"result": "PENDING",
"type": "MERCHANT_ID"
}
],
"state": "PROCESSING",
"sub_mchid": "999968479",
"transaction_id": "4200000012202203235765130087"
}
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证