When a refund is needed due to the buyer or seller within a period after the transaction, the seller can return the payment to the buyer through the Refund API. WeChat Pay will return the payment to the buyer's account in accordance with the refund rules after receiving the refund request and completing the verification.
Tips：
Orders placed over one year ago are not eligible for refund.
WeChat Pay allows for refunds to be made in multiple installments for a single transaction, up to 50 times. For multiple refunds, the merchant order number of the original payment order must be provided and different refund number must be set. The total refund amount applied cannot exceed the order amount. If a refund fails, please resubmit it without changing the refund number and use the original merchant refund number.
The frequency limit for error or invalid requests is 6qps, which means that the number of abnormal or erroneous refund requests should not exceed 6 per second.
The number of partial refunds for each payment order cannot exceed 50 times.
If a user requests multiple refunds, it is recommended to process them in different batches to avoid concurrent refunds that may result in refund failures.
The return of the refund application interface only represents the acceptance status of the transaction. To confirm the success of a refund, you need to obtain the result through the refund query interface.
The refund frequency limit for orders placed over a month ago is 5000/min.
Requests for multiple refunds for the same order must be separated by 1 minute.
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
Merchant ID
mchid
string[1,32]
Yes
Body Merchant ID assigned by WeChat Pay Note: Only for Common mode Example: 1900000109
APPID
appid
string[1,32]
Yes
Body APPID corresponding to the mobile app applied for by the merchant on the WeChat Open Platform Note: Only for Common mode Example: wx8888888888888888
Institution's Merchant ID
sp_mchid
string[1,32]
Yes
Body Merchant ID assigned to institutions by WeChat Pay Note: Only for Institutional mode Example: 1900000100
Sub-merchant ID
sub_mchid
string[1,32]
Yes
Body Merchant ID assigned to sub-merchants by WeChat Pay Note: Only for Institutional mode Example: 1900000109
Organization APPID
sp_appid
string[1,32]
Yes
Body APPID corresponding to the Service Account applied for by the merchant on the WeChat Official Accounts Platform Note: Only for Institutional mode Example: wx8888888888888888
Sub-merchant APPID
sub_appid
string[1,32]
No
Body APPID corresponding to the mobile app applied for by the sub-merchant on the WeChat Open Platform When Quick pay or Native Payment or Official account payment, please use appid of the merchant’s official account. When Mini program payment, please use the appid of the merchant’s mini program. When In-APP payment, please use the appid of the merchant’s APP. Note: Only for Institutional mode Example: wx8888888888888888
WeChat order No.
transaction_id
string[1,32]
Choose one
Body WeChat order No. corresponding to the original payment transaction Example: 1217752501201407033233368018
Merchant order No.
out_trade_no
string[1,32]
Body Order No. corresponding to the original payment transaction Example: 1217752501201407033233368018
Merchant refund No.
out_refund_no
string[1,64]
Yes
Body The unique refund No. within the merchant system, which can only contain numbers, uppercase and lowercase letters, and "_", "-", "|", "*" and "@". Only one refund is available for multiple requests under the same refund No. Example: 1217752501201407033233368018
Refund reason
reason
string[1,80]
No
Body If the merchant passes the information, the refund reason will be displayed in the refund message sent to the user. Example: The item has been sold out.
Refund source
source
No
string[1,30]
Body REFUND_SOURCE_UNSETTLED_FUNDS：Refund with unsettled funds (default) REFUND_SOURCE_RECHARGE_FUNDS：Refund with available balance Example：REFUND_SOURCE_UNSETTLED_FUNDS Note: This field is not applicable to the Funds Distribution business.
Order amount
amount
object
Yes
Body Information on the order amount. For more information, see the description below.
Order amount
Name
Variable Name
Type
Required
Description
Refund amount
refund
int
Yes
Refund amount. The minimum unit of the currency can only be an integer. The refund amount cannot exceed the original order amount. If a voucher was used, the backend will refund proportionally.
Example: 888
Original order amount
total
int
Yes
The total order amount of the original transaction. The minimum unit of the currency can only be an integer. See "Payment amount" for details. Example: 888
Refund currency
currency
string[1,16]
Yes
Three-letter code in accordance with ISO 4217. The refund currency must be the same as the priced currency. See "Currency Type" for the currency list.
Example: HKD
Refund Source & Amount
from
array
No
This parameter is used to specify the fund source and amount for cross-border funds-distribution orders. If this parameter is not specified for a funds-distribution order, the refund will be made from the undistributed refundable balance of the order by default, and the shortfall will be made up by the advance refund amount. The specific fund source and amount are subject to the "from" field in the response parameter.
Parameter passing needs to meet the following conditions:
The sum of the fund amount from the advance refundable balance and the fund amount from the undistributed refundable balance of the order is equal to the refund amount;
The fund sources cannot be duplicated.
If any of the above conditions are not met, an error will be returned.
Refund Source & Amount
Name
Variable Name
Type
Required
Description
Fund Source
fund_source
string[1,32]
Yes
The source of the refund, which can be any of the enumerated values below. Enumerated values: FUNDS_REFUNDABLE_BALANCE : Advance refundable balance ORDER_REFUNDABLE_BALANCE : Undistributed refundable balance
Example：ORDER_REFUNDABLE_BALANCE
Fund Amount
amount
int
Yes
The amount funded from a source, which can only be an integer in the smallest unit of currency.
Example：888
Refund notification URL
notify_url
string[1,256]
No
Body The callback address to receive WeChat Pay refund status changes asynchronously. The notification URL must be accessible by external networks, and is not allowed to carry any parameters. Use the HTTPS protocol URL. Example: https://www.weixin.qq.com/wxpay/pay.php
Request Example
Scenario 1: Regular order refund request
1{2"sp_appid":"wx2421b1c4370ec43b",3"sub_appid":"1900000109",4"sp_mchid":"10000100",5"sub_mchid":"20000100",6"transaction_id":"1008450740201411110005820873",7"out_refund_no":"R20150806125346",8"amount":{9"refund":50,10"total":100,11"currency":"HKD"12},13"reason":"The item has been sold out.",14"source":"REFUND_SOURCE_UNSETTLED_FUNDS"15}
Scenario 2: Request for refund of designated funding source for split order
1{2"sp_appid":"wx7bc98d929da735fe",3"sp_mchid":"999952224",4"sub_mchid":"999968479",5"out_trade_no":"20220724trade004",6"out_refund_no":"20220724trade004refund001",7"amount":{8"currency":"CNY",9"refund":500,10"total":1000,11"from":[{12"fund_source":"FUNDS_REFUNDABLE_BALANCE",13"amount":20014},15{16"fund_source":"ORDER_REFUNDABLE_BALANCE",17"amount":30018}//#Note: The sum of the funding source amounts must be equal to the total refund amount， just 200 + 300 = 50019]20},21"reason":"The item has been sold out."22}
3. Response Parameters
Response for successful request:
Name
Variable Name
Type
Required
Description
WeChat Pay refund order No.
id
string[1,32]
choose one to submit
WeChat Pay refund order No. Example: 1217752501201407033233368018
Merchant refund No.
out_refund_no
string[1,64]
Returned refund order No. Example: 1217752501201407033233368018
Refund creation time
create_time
string[1,64]
Yes
Refund acceptance time Example: 2018-06-08T10:34:56+08:00
Refund amount
amount
object
Yes
Information on the refund amount. For more information, see the description below.
Refund amount
Name
Variable Name
Type
Required
Description
Refund amount
refund
int
Yes
Refund amount. The minimum unit of the currency can only be an integer. The refund amount cannot exceed the original order amount. If a voucher was used, the backend will refund proportionally.
Example: 888
Refund currency
currency
string[1,16]
Yes
Three-letter code in accordance with ISO 4217.
Example: CNY
Refund amount to user
payer_refund
int
Yes
The amount refunded to the user, excluding all voucher amount
Example: 888
Payment currency
payer_currency
string[1,16]
Yes
Three-letter code in accordance with ISO 4217.
Example: CNY
Settlement Currency Refund Amount
settlement_refund
int
Yes
The refund amount corresponding to the merchant's settlement currency, the smallest unit of the currency, which can only be an integer.
Example: 888
Settlement Currency
settlement_currency
string[1,16]
Yes
Settlement currency, a three-letter code that conforms to the ISO 4217 standard, see the currency type on the currency list.
Example: HKD
Exchange rate
exchange_rate
object
Yes
Exchange rate information
Exchange rate
Name
Variable Name
Type
Required
Description
Exchange rate type
type
string[1,16]
No
When the priced currency and the settlement currency are the same, type="USERPAYMENT_RATE", i.e. the exchange rate between the [original payment] priced currency and the payment currency.
When the priced currency and the settlement currency are different, type="SETTLEMENT_RATE", i.e. the exchange rate between the priced currency and the settlement currency.
Example: SETTLEMENT_RATE
Exchange rate value
rate
int
No
The rate value is the exchange rate multiplied by the 8th power of 10. If the exchange rate is 1, then the exchange rate value is 100,000,000; if the exchange rate is 6.5, then the exchange rate value is 650,000,000.
Example: 8000000
Refund Source & Amount
from
array
No
This parameter is used to specify the fund source and amount for cross-border funds-distribution orders. If this parameter is not specified for a funds-distribution order, the refund will be made from the undistributed refundable balance of the order by default, and the shortfall will be made up by the advance refund amount. The specific fund source and amount are subject to the "from" field in the response parameter.This parameter applies to usage scenarios meeting the following conditions:
The order is a cross-border funds-distribution order. Do not specify this parameter for non-cross-border orders.
Parameter passing needs to meet the following conditions:
The sum of the fund amount from the advance refundable balance and the fund amount from the undistributed refundable balance of the order is equal to the refund amount;
The fund sources cannot be duplicated.
If any of the above conditions are not met, an error will be returned.
Refund Source & Amount
Name
Variable Name
Type
Required
Description
Fund Source
fund_source
string[1,32]
Yes
The source of the refund, which can be any of the enumerated values below. Enumerated values: FUNDS_REFUNDABLE_BALANCE : Advance refundable balance ORDER_REFUNDABLE_BALANCE : Undistributed refundable balance
Example：ORDER_REFUNDABLE_BALANCE
Fund Amount
amount
int
Yes
The amount funded from a source, which can only be an integer in the smallest unit of currency.
Example：888
Discount refund details
detail
array
No
Discount refund details. For more information, see the description below.
COUPON：Vouchers, which are a kind of top-up vouchers that require fund settlement (the voucher currency of overseas merchants is the same as the payment currency). DISCOUNT：Discount vouchers, which are a kind of top-up-free discount vouchers that require no fund settlement (the voucher currency of overseas merchants is the same as the priced currency).
Example: DISCOUNT
Discount voucher price
amount
int
No
The amount for which the user enjoys a discount (Voucher amount = Amount contributed by WeChat + Amount contributed by the merchant + Amount contributed by others)
Example: 5
Voucher refund amount
refund_amount
int
No
Voucher amount refunded proportionally
Example: 5
Currency type
currency
string[1,16]
Yes
Three-letter code in accordance with ISO 4217.
Example: CNY
Note:goods_remark is a remark field that is returned unchanged. goods_tag is an order discount tag to distinguish whether an order can be discounted. Both fields are set when the voucher is configured in the WeChat backend.
Response for failed request:
Name
Variable Name
Type
Required
Description
Returned status code
code
string[1,32]
Yes
Error code. See the error code list for the enumerated values.
Returned information
message
string[1,256]
Yes
Returned message. It indicates the reason for the error if not empty.
Detailed error description
detail
object
No
It is returned when code is PARAM_ERROR. Details will be described below.
Detailed error description
Name
Variable Name
Type
Required
Description
The location of incorrect parameter
field
string[1,256]
Yes
If the incorrect parameter is in the JSON for request body, it is populated with the JSON Pointer pointing to this parameter. If the incorrect parameter is in the request URL or querystring, it is populated with the variable name of this parameter.
Value of the incorrect parameter
value
string[1,256]
Yes
Value of the incorrect parameter
Cause of error
issue
string[1,256]
Yes
Cause of error
Location of the incorrect parameter
location
string[1,256]
No
body: The incorrect parameter is in the JSON for request body url: The incorrect parameter is in the request URL query: The incorrect parameter is in the querystring of the request
1{2"code":"INVALID_REQUEST",3"message":"Parameter format verification error",4"detail":{5"field":"#/properties/payer",6"value":"1346177081915535577",7"issue":"Not in line with ALLOF schema",8"location":"body"9}10}
4. Error Codes
Error Message
Description
Solution
SYSTEM_ERROR
Errors returned from the API
Do not change the merchant refund No. Call the API again using the same parameters. Otherwise it may cause financial loss.
INVALID_REQUEST
Invalid request
Check your program based on the error message returned by the API.
RESOURCE_NOT_EXISTS
Record not found
Record not found. Modify the parameter and try again.
BIZERR_NEED_RETRY
Refund service process error. The merchant needs to trigger a retry to resolve.
Do not change the merchant refund No. Call the API again using the same parameters. Otherwise it may cause financial loss.
TRADE_OVERDUE
The order refund period has expired.
Choose another method to refund.
ERROR
Service error
Specific cause of the error will be returned. Process properly according to the actual returned result.
USER_ACCOUNT_ABNORMAL
Refund request failed
This status indicates that the refund request failed, and the merchant can process the refund on its own.
INVALID_REQ_TOO_MUCH
Too many invalid requests
Check whether the service is normal. Try again in 1 minute after confirming that the service is normal.
NOT_ENOUGH
Insufficient balance
This status indicates that the refund request failed, and the merchant can process it according to the specific error prompt.
INVALID_TRANSACTIONID
Invalid transaction_id
Invalid request parameter. Check whether the original transaction No. exists and whether the API for initiating payment transaction returns failure.
PARAM_ERROR
Invalid parameter
Invalid request parameter. Re-check and then call the refund request again.
APPID_NOT_EXIST
APPID does not exist.
Check whether APPID is correct.
MCHID_NOT_EXIST
MCHID does not exist.
Check whether MCHID is correct.
REQUIRE_POST_METHOD
Use post method.
Check whether the request parameter is submitted via post method.
SIGN_ERROR
Signature error
Check if signature parameters and methods meet the algorithm requirements.
FREQUENCY_LIMITED
Rate limit
The refund is not accepted. Try again after lowering the rate.The refund is not accepted. Lower the rate and try again. Do not change the order No.
