API Dictionary / Funds Distribution(Bill and Fund) / API for Obtaining the Refund Bill Download URL

API for Obtaining the Refund Bill Download URL

Latest update time：2023.10.20 Release notes

WeChat Pay provides funds-distribution refund files by day. Merchants can call this API to get the download URL for billing files. The files include the amount, time, and other information of the funds-distribution refunds, so merchants can check the status of transfers.

Tips：

• Unsuccessful funds-distribution requests will not appear in bills.

• Amounts in the bills are in CNY

• The Profit-sharing Downloading Reconciliation API can only download bills within 90 days.

1. API Instructions

Applicable to：Common mode Institutional mode

Request URL：https://apihk.mch.weixin.qq.com/v3/global/profit-sharing/refunds/bill-download-url

Request method：GET

Pathparameter is a path parameter.

Queryparameter needs to be passed in the request URL.

Bodyparameter 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	QueryIf a merchant is a directly linked merchant: - The field can be left empty. If the merchant is a service provider or institution: - If the field is left empty, all bills of the service provider or institution will be returned by default. - If you need to download the bills of a certain sub-merchant, you must specify the field. Example：19000000001
Bill Date	bill_date	string[10, 10]	Yes	QueryThe Profit-sharing Downloading Reconciliation API can only download bills within 90 days. Example：2020-01-01an

Request Eample：

URL


https://api.mch.weixin.qq.com/v3/global/profit-sharing/refunds/bill-download-url?sub_mchid=19000000001&bill_date=2020-01-01


{
    "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
    "appid": "wx78898sdfwe9888835", 
    "type": "PERSONAL_OPENID", 
    "sub_mchid": "999968480"
}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

3. Return Parameters

Name	Variable Name	Type	Required	Description
Download URL	download_url	string[1, 2048]	是	The URL for downloading the billing files. The URL is valid for 30s. Example：https://api.mch.weixin.qq.com/v3/bill/downloadurl?token=xxx

Response Example:

SUCCESS


{
  "download_url": "https://api.mch.weixin.qq.com/v3/bill/downloadurl?token=xxx"
}


{
    "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
    "appid": "wx78898sdfwe9888835", 
    "type": "PERSONAL_OPENID", 
    "sub_mchid": "999968480"
}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

Notes on File Format

• A billing file consists of two parts: overview and details. Each part includes a header and a certain number of lines of data.

• In the bill details, each line corresponds to a funds-distribution. A character is inserted before each data entry to prevent Excel from treating it as a number. If you need to sum amounts, you can remove the character using Replace All.

• The headers are as follows: Refund apply time, Refund success time, Wechat refund number(refund_id), Vendor refund number(out_refund_no), Wechat order number(transaction_id), Vendor order number(out_transaction_id), Refund amount(refund_fee), Currency type, Coupon refund amount, Payer's refund amount, Payer's refund currency type, Rate, Refund source, Refund source type, Refund source amount, Refund source fee in CNY, Refund settlement currency type, Refund exchange rate, Refund source settlement amount, and Refund source fee in settlement currency type. See the following table for the definitions.

Variable	Field Name	Description
Refund apply time	Refund Application Time	The time at which the refund is initiated for the transaction. The format is YYYY-MM-DD HH:MM:SS. Example：2015-01-01 10:00:00
Refund success time	Refund Completion Time	The time at which the refund for the transaction is successful. The format is YYYY-MM-DD HH:MM:SS. Example：2015-01-01 10:00:00
Wechat refund number(refund_id)	WeChat Refund Number	The refund number that WeChat Pay assigned to the refund. Example：5050000008201712143733500002
Vendor refund number(out_refund_no)	Merchant Refund Number	The refund number that is entered by the merchant when the refund is initiated. Example：ST175HQWa0
Wechat order number(transaction_id)	WeChat Order Number	The order number that WeChat Pay assigned to the order corresponding to the refund. Example：4200000008201712143733500001
Vendor order number(out_transaction_id)	Merchant Order Number	The merchant order number of the order passed by the merchant (or the order corresponding to the refund). The field corresponds to the out_trade_no field of the order placement API. Example：test1
Refund amount(refund_fee)	Refund Amount	The refund amount in the priced currency. Example：0.00
Currency type	Priced Currency	The three-letter ISO 4217 code for the priced currency. Example：CNY
Coupon refund amount	Voucher or Discount Amount	The amount of the WeChat Pay voucher used for the order, including prepaid and non-prepaid vouchers (CNY, to two decimal places). Example：0.00
Payer's refund amount	Refund Amount in Payment Currency	The total amount of the refund in the user's payment currency. Example：0.00
Payer's refund currency type	Payment Currency Type	The three-letter ISO 4217 code for the user's payment currency. Example：CNY
Rate	Fee Rate	The fee rate used to calculate this transaction (in percent). Example：0.50%
Refund source	Refund Source	The refund source of a funds-distribution. Enumerated values: 1. FUNDS_REFUNDABLE_BALANCE: Advance refundable balance 2. ORDER_REFUNDABLE_BALANCE: Undistributed refundable balance Example：ORDER_REFUNDABLE_BALANCE
Refund source type	Refund Source Type	The refund source type of a funds-distribution. There are two types as follows: 1. SINGLE_SOURCE: The refund uses a single source. For example, an amount of 100 CNY is entirely refunded from ORDER_REFUNDABLE_BALANCE. 2. PACKAGE: The refund combines sources. For example, to refund 100 CNY, 30 CNY is refunded from ORDER_REFUNDABLE_BALANCE and 70 CNY is refunded from FUNDS_REFUNDABLE_BALANCE. If the refund source type is "PACKAGE", multiple records will appear in the refund bill. Enumerated values: 1. PACKAGE 2. SINGLE_SOURCE Example：PACKAGE
Refund source amount	Refund Amount (CNY)	The refund amount of each "Refund Source" item in a refund bill. Example：0.00
Refund source fee in CNY	Refund Fee (CNY)	The fee incurred for each refund amount in a refund bill. Example：-0.02
Refund settlement currency type	Refund Settlement Currency	The three-letter ISO 4217 code for the currency in which the merchant initiated the refund. Example：CNY
Refund exchange rate	Refund Exchange Rate	Take the exchange rate between the foreign currency and CNY and multiply it by 10 to the power of 8 to get this value. For example, if the exchange rate between USD and CNY is 6.5, the refund exchange rate is 650000000. Example：650000000 Note: The refund exchange rate is calculated based on the market exchange rate when the refund is completed, which is provided by the relevant bank.
Refund source settlement amount	Refund Amount for Settlement	The foreign currency amount for settlement corresponding to each refund amount in a refund bill. Notes: 1. If the refund source is FUNDS_REFUNDABLE_BALANCE, funds that are waiting to cross the border are used to net the refund, and the foreign currency amount for settlement needs to be calculated. 2. If the refund source is ORDER_REFUNDABLE_BALANCE, the funds are not of the outbound portion and will not affect the calculation, so the field can be left Example：0.00
Refund source fee in settlement currency type	Refund Fee in Settlement Currency	The foreign currency fee for settlement corresponding to each refund amount in a refund bill. 1. If the refund source is FUNDS_REFUNDABLE_BALANCE, the foreign currency fee needs to be calculated. 2. If the refund source is ORDER_REFUNDABLE_BALANCE, the field can be left empty. Example：-0.00

Example Fields in a Bill


Refund apply time,Refund success time,Wechat refund number(refund_id),Vendor refund number(out_refund_no),Wechat order number(transaction_id),Vendor order number(out_transaction_id),Refund amount(refund_fee),Currency type,Coupon refund amount,Payer's refund amount,Payer's refund currency type,Rate,Refund source,Refund source type,Refund source amount,Refund source fee in RMB,Refund settlement currency type,Refund exchange rate,Refund source settlement amount,Refund source fee in settlement currency type
`2022-07-26 23:08:30,`2022-07-26 23:08:38,`50202102632022072601880685005,`test00011115_001,`4200000002202207268931261193,`test00011115,`400.00,`CNY,`20.00,`400.00,`CNY,`0.50%,`FUNDS_REFUNDABLE_BALANCE,`PACKAGE,`200.00,`-1.00000,`HKD,`86500000,`231.21000,`-0.87000


{
    "account": "of8YZ6LPmjDmYAqdobIvwTdQQjR8",
    "appid": "wx78898sdfwe9888835", 
    "type": "PERSONAL_OPENID", 
    "sub_mchid": "999968480"
}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

4. Error Codes

Error Codes	Error Message	Description	Solution
400	NO_STATEMENT_EXIST	The requested billing file does not exist.	Check whether the current merchant account has a successfully processed funds-distribution order within the specified date.
400	STATEMENT_CREATING	Generating the bill.	Check whether the current merchant account has a successfully processed funds-distribution order within the specified date, and if so, download it again after 10:00 am on T+1 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.
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.

Page Navigation

Language

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Payments

Funding Products

Other Products

API for Obtaining the Refund Bill Download URL

1. API Instructions

2. Request Parameters

Request Eample：

3. Return Parameters

Response Example:

Notes on File Format

4. Error Codes