Submit Refund

Update Time:2025.03.27

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.


1. API intro

Applicable object: Common mode Institutional mode

Request URL: https://apihk.mch.weixin.qq.com/v3/global/refunds

Request method: POST

rate limitt:150qps

 

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

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

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": 200
14			},
15			{
16				"fund_source": "ORDER_REFUNDABLE_BALANCE",
17				"amount": 300
18			}  //#Note: The sum of the funding source amounts must be equal to the total refund amount, just 200 + 300 = 500
19		]
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

Discount refund details

detail

array

No

Discount refund details. For more information, see the description below.

Discount refund details

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

Response Example:

No Accounts Order Return Example

1{
2    "id": "50202002642022072801898085012",
3    "out_refund_no": "20220724trade003refund001",
4    "create_time": "2022-07-28T15:44:07+08:00",
5    "amount": {
6        "refund": 500,
7        "currency": "CNY",
8        "payer_refund": 250,
9        "payer_currency": "CNY",
10        "settlement_refund": 578,
11        "settlement_currency": "HKD",
12        "exchange_rate": {
13            "type": "SETTLEMENT_RATE",
14            "rate": 86500000
15        }
16    },
17    "detail": [
18        {
19            "promotion_id": "11006096615",
20            "scope": "GLOBAL",
21            "type": "COUPON",
22            "amount": 500,
23            "refund_amount": 250,
24            "currency": "CNY"
25        }
26    ]
27}

Accounts Order Return Example

1{
2    "id": "50201702652022072801898085013",
3    "out_refund_no": "20220724trade004refund001",
4    "create_time": "2022-07-28T15:51:57+08:00",
5    "amount": {
6        "refund": 500,
7        "currency": "CNY",
8        "payer_refund": 250,
9        "payer_currency": "CNY",
10        "settlement_refund": 578,
11        "settlement_currency": "HKD",
12        "exchange_rate": {
13            "type": "SETTLEMENT_RATE",
14            "rate": 86490000
15        },
16        "from": [
17            {
18                "fund_source": "ORDER_REFUNDABLE_BALANCE",
19                "amount": 300
20            },
21            {
22                "fund_source": "FUNDS_REFUNDABLE_BALANCE",
23                "amount": 200
24            }
25        ]
26    },
27    "detail": [
28        {
29            "promotion_id": "11006096908",
30            "scope": "GLOBAL",
31            "type": "COUPON",
32            "amount": 500,
33            "refund_amount": 250,
34            "currency": "CNY"
35        }
36    ]
37}

Exception Example

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.

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.