Menu
User login
Product CapabilityAPI DictionaryInterface RulesAccess SpecificationFAQsTermsUpdate Log

Unfreezing Remaining Funds

Update Time：2025.01.07
|

For transactions that do not require funds-distribution, call the API directly to unfreeze all the transaction amount to the sponsor account (original transaction funds settlement account); After the funds-distribution interface is called, and when remaining funds need to be unfrozen, call the API to unfreeze all remaining funds to the sponsor.

Tips：

● 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;

● After the return of this API is successful, the amount of unfrozen funds outbound, 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.

1. API Intro

Applicable object： Common mode Institutional mode

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

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

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

Funds-distribution description

description

string[1, 80]

Yes

Body Reason description of funds-distribution, to be reflected in the funds-distribution record
Example: Unfreeze all remaining funds

Request Example

JSON

1{
2  "description": "Unfreeze all remaining funds",
3  "out_order_no": "P20150806125346",
4  "sub_mchid": "1900000109",
5  "transaction_id": "4208450740201411110007820472"
6}

 

3. Response Parameters

Name

Variable Name

Type

Required

Description

Sub-merchant ID

sub_mchid

string[1, 32]

No

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

Return Example

SUCCESS

1{
2    "order_id": "7100000751202203238029563456088",
3    "out_order_no": "P20150806125346",
4    "receivers": [
5      {
6        "account": "999952224", # sponsor merchant ID
7        "amount": 995,
8        "create_time": "2022-03-23T17:59:23+08:00",
9        "currency": "CNY",
10        "description": "Unfreeze all remaining funds",
11        "detail_id": "7200000751202203238029563456171",
12        "detail_type": "UNFREEZE_TO_SPONSOR",
13        "rate_value": 83640300,
14        "result": "PENDING",
15        "settlement_amount": 1189,
16        "settlement_currency": "HKD",
17        "type": "MERCHANT_ID"
18      }
19    ],
20    "state": "PROCESSING",
21    "sub_mchid": "1900000109",
22    "transaction_id": "4208450740201411110007820472"
23  }

ERROR

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

 

4. Error Code

Error Codes

Error Message

Description

Solution

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

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

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

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

403

NOTENOUGH

The funds amount to be distributed is insufficient at the time of request

The current remaining funds amount to be distributed of the transaction can be obtained through [Remaining Funds Amount to be Distributed Query API]

500

SYSYTEMERROR

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

 

 

1. API Intro
2. Request Parameters
Request Example
3. Response Parameters
Return Example
4. Error Code
Lang
TOP