Latest update time：2020.04.30 Release notes
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.
1. Orders that have been completed for more than one year cannot be submitted for refund.
2. WeChat Pay supports multiple refunds for a single transaction. For multiple refunds under a single order, you need to submit the merchant order No. and set different refund Nos. The total amount of the refund cannot exceed the order amount. For re-submission after a failed refund request, do not change the refund No., but use the original merchant refund No.
3. Request rate limit: 150qps. Generally, the refund requests should be no more than 150 per second. Incorrect or invalid request rate limit: 6qps, meaning no more than 6 unusual or incorrect refund requests per second.
4. Over 50 partial refunds for each paid order shall not be allowed.
Request URL: https://api.mch.weixin.qq.com/hk/v3/refunds
Request method: POST
Applicable object:Common modeInstitutional mode
API Rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3
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 |
|---|---|---|---|---|
| Merchant ID | mchid | string(32) | Yes | body Merchant ID assigned by WeChat Pay Note: Only forCommon mode Example：1900000109 |
| APPID | appid | string(32) | Yes | body APPID corresponding to the mobile app applied for by the merchant on the WeChat Open Platform Note: Only forCommon mode Example：wx8888888888888888 |
| Institution's Merchant ID | sp_mchid | string(32) | Yes | query Merchant ID assigned to institutions by WeChat Pay Note: Only forInstitutional mode Example：1900000100 |
| Sub-merchant ID | sub_mchid | string(32) | Yes | body Merchant ID assigned to sub-merchants by WeChat Pay Note: Only forInstitutional mode Example：1900000109 |
| Organization APPID | sp_appid | string(32) | Yes | query APPID corresponding to the Service Account applied for by the merchant on the WeChat Official Accounts Platform Note: Only forInstitutional mode Example：wx8888888888888888 |
| Sub-merchant APPID | sub_appid | string(32) | No | body APPID corresponding to the mobile app applied for by the sub-merchant on the WeChat Open Platform When Quick pay or QR code 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 forInstitutional mode Example：wx8888888888888888 |
| WeChat order No. | transaction_id | string(32) | Choose one | body WeChat order No. corresponding to the original payment transaction Example：1217752501201407033233368018 |
| Merchant order No. | out_trade_no | string(32) | body Order No. corresponding to the original payment transaction Example：1217752501201407033233368018 |
|
| Merchant refund No. | out_refund_no | string(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(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 | string(30) | No | body REFUND_SOURCE_UNSETTLED_FUNDS：Refund with unsettled funds (default) REFUND_SOURCE_RECHARGE_FUNDS：Refund with available balance Example：REFUND_SOURCE_UNSETTLED_FUNDS |
| + Order amount | amount | object | Yes | body Information on the order amount. For more information, see the description below. |
| Refund notification URL | notify_url | string(256) | No | bodyThe 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 |
{
"sp_appid": "wx2421b1c4370ec43b",
"sub_appid": "1900000109",
"sp_mchid": "10000100",
"sub_mchid": "20000100",
"transaction_id": "1008450740201411110005820873",
"out_refund_no": "R20150806125346",
"amount" : {
"refund": 50,
"total":100,
"currency":"HKD"
},
"reason": "The item has been sold out.",
"source": "REFUND_SOURCE_UNSETTLED_FUNDS"
}
| Name | Variable Name | Type | Required | Description |
|---|---|---|---|---|
| Returned status code | code | string(32) | Yes | Error code. See the error code list for the enumerated values. Example：INVALID_REQUEST |
| Returned message | message | string(256) | Yes | Returned message. It indicates the reason for the error if not empty. Example：Parameter format verification error |
| + Detailed error description | detail | object | No | It is returned when code is PARAM_ERROR. Details will be described below. |
| Name | Variable Name | Type | Required | Description |
|---|---|---|---|---|
| WeChat Pay refund order No. | id | string(32) | Yes | WeChat Pay refund order No. Example：1217752501201407033233368018 |
| Merchant refund No. | out_refund_no | string(64) | Yes | Returned refund order No. Example：1217752501201407033233368018 |
| Refund creation time | create_time | string(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. |
| + Discount refund details | detail | array | No | Discount refund details. For more information, see the description below. |
{
"id": "2008450740201411110000174436",
"out_refund_no": "R20150806125346",
"create_time": "20141111170042",
"amount": {
"refund": 50,
"currency": "CNY",
"payer_refund": 49,
"payer_currency": "HKD",
"exchange_rate" : {
"type": "SETTLEMENT_RATE",
"rate": 8000000
}
},
"detail": [
{
"promotion_id":"109519",
"scope":"GLOBAL",
"type":"COUPON",
"amount": 1,
"refund_amount": 1,
"currency":"HKD"
}
]
}
| Name | Description | Solution |
|---|---|---|
| SYSTEMERROR | 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. |
| 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. |
| NOTENOUGH | 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. |
| SIGNERROR | 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. |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证