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

Remaining Refundable Amount Query

Update Time：2025.03.03

If a merchant initiates funds-distribution several times for a funds-distribution payment order, this API can be used to query the remaining refundable amount of this order.

Tips：

After a funds-distribution payment order is paid, the order funds will be frozen in a specific merchant's account, and the merchant can distribute or unfreeze the funds by executing the funds-distribution command or the unfreezing remaining funds command or refund the specific user by calling the merchant refund API.

The amount that the merchant can use to distribute or unfreeze can be found by querying the remaining amount to be distributed (the amount is the amount after deducting the platform service charge from the order settlement).
The remaining refundable amount provided by the API refers to the amount of payment returned to the user (including the corresponding proportion of the service charge returned by the platform).

For example, if the amount of an order is 100 CNY and the service charge ratio is 1%, the service charge is 1 CNY. In this case, the remaining amount of the order to be distributed is 99 CNY, and the remaining refundable amount is 100 CNY.

If the merchant distributes 49.5 CNY to its partner via the Request funds-distribution API, the remaining amount to be distributed for the order is: 99-49.5=49.5 CNY, the remaining refundable amount is 49.5 + 49.5 / (100 (1 - 1%)) = 50 CNY (the remaining amount to be distributed + the refundable service charge).

The service charge is subject to the value returned by this API. The platform side will guarantee that when an order is fully refunded, the returned service charge is equal to the amount charged for the original order payment.

1. API Instructions

Applicable to：Common mode Institutional mode

Request URL： https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/transactions/{transaction_id}/refundable-amounts

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	Query indicates the merchant ID assigned by WeChat Pay, which should be consistent with the Sub-Merchant ID of the WeChat Pay order. (Not required for directly linked merchants, required for service providers/institutions) Example：1900000109
WeChat Pay Order Number	transaction_id	string[1, 32]	Yes	Path indicates WeChat Pay order number Example：4208450740201411110007820472

Request Example：

URL

1https://api.mch.weixin.qq.com/v3/global/profit-sharing/transactions/4208450740201411110007820472/refundable-amounts?sub_mchid=1900000109

3. Return Parameters

Name	Variable Name	Type	Required	Description
WeChat Pay Order Number	transaction_id	string[1, 32]	Yes	WeChat Pay order number Example: 4208450740201411110007820472
Remaining Refundable Order Amount	refundable_amount	int	Yes	The order amount frozen in the merchant account for refund, which can only be an integer in the smallest unit of currency (currently in CNY Fen). Note: Using frozen order amount as refund will decrease its remaining distributable amount. Example: 1000
Currency Type	currency	string[1, 10]	Yes	Only the Chinese yuan "CNY" is supported. Example: CNY
The amount of the remaining advance refund available for an order	funds_refundable_amount	int	No	The amount of the remaining Advance Refund quota available for an order(CNY, in Fen). Note: Initiating advance refund for an order will decrease its remaining available advance refund amount. Example：100

Response Example:

SUCCESS

1{
2  "currency": "CNY",
3  "refundable_amount": 1000,
4  "transaction_id": "4208450740201411110007820472"
5  "funds_refundable_amount": "100"
6}

4. Error Codes

Error Codes	Error Message	Description	Solution
400	INVALID_REQUEST	This order does not support ledger splitting	Please check if the WeChat payment order number is filled in incorrectly and confirm that the call to the order API has been successful before executing call to the accounting mark API
403	NO_AUTH	The merchant has not signed up for the overseas funds-distribution function.	See the product process and preparation before access, and check that the merchant has funds-distribution permission before initiating a request.
403	NO_AUTH	The merchant has enabled the funds-distribution function and is waiting for it to take effect. (In most cases, the function will take effect only on the next day.)	You cannot initiate a funds-distribution on the day that you enable the function. Initiate the request on the next day.
403	NO_AUTH	The merchant parent-child relationship does not exist. Initiate the request with the correct Sub-Merchant ID.	Check if the Sub-Merchant ID (sub_mchid) is correct.
400	INVALID_REQUEST	The merchant information is inconsistent with the order merchant information.	Check if the Sub-Merchant ID (sub_mchid) or WeChat Pay Order Number (transaction_id) is correct.
500	SYSYTEM_ERROR	The WeChat Pay order fund freezing process specified by the merchant's funds-distribution initiation request has not been completed. Try again later.	The fund freezing process for the funds-distribution payment order will be triggered once the user's payment is completed. It is recommended that the merchant try it after 3 to 5 min. \|