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

Payments
- Quick Pay
- Native Payment
- JSAPI Payment
- In-App Payment
- Mini Program Payment
- H5 Payment
- Auto-Debit Payment
Funding Products
- Funds Distribution(Transaction)
- Funds Distribution(Operate)
- Funds Distribution(Refund)
- Funds Distribution(Bill and Fund)
Other Products
- Merchant Onboard
- H5 Payment Authorization Application
- Customs Declaration

Refund Notification

Update Time：2025.03.21

After completing refund, the WeChat payment system will send the refund result to the Merchant.

Tips：

The same notification may be sent to the merchant system for multiple times. The merchant system must be able to process repeated notifications properly. It is recommended that when a notification is received and processed, check the status of the corresponding business data first, and then analyze whether it is processed. If not, then process it; if yes, return the processed result. Before the status check and process of business data, perform concurrent control of these data with data locks to avoid data corruption caused by reentrant functions.

If the wechat pay callback is not received after all notification frequencies (4 hours), the merchant need to call the 【Query Order API】to confirm the order status.

Note：The merchant system must perform signature verification for the refund result notification, and verify whether the returned refund amount is consistent with that on the merchant side to prevent any possible capital loss caused by "false notifications" due to data leakage.

1. API intro

Applicable object: Common mode Institutional mode

Request URL: The URL is set by the parameter notify_url submitted in [Submit Refund API] and the https protocol is required. If the URL cannot be accessed, the merchant will not receive any WeChat notifications. The URL must be directly accessible without any parameters. For example: notify_url: http://pay.weixin.qq.com/wxpay/123456789

2. Notification Rules

After the refund status changes, WeChat will send the refund results to the merchant.

When notifying the interaction to the backend, if the response received by WeChat is unsuccessful or timeout, WeChat considers it as a notification failure and will send it again by following certain strategies to maximize the success rate, but WeChat does not guarantee a successful notification. （Notification frequency:15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - in total 24h4m）.

3. Notification Message

For refund result notifications, access the notification URL set up by the merchant with the `POST` method, and the notification data is transmitted through the request body (BODY) in the `JSON` format. The notification data contains the details of the encrypted refund result.

The procedure of how to decrypt the notification data is described as follows.

Obtain the merchant's notification key from the merchant platform, and record it as `key`.
Obtain the corresponding parameters `nonce` and `associated_data` for the algorithm described in `resource.algorithm` (which is `AEAD_AES_256_GCM`).
Decrypt the ciphertext `resource.ciphertext` with `key`, `nonce`, and `associated_data`, to obtain the resource objects in the Json format.

Notice

For the information on the API of the algorithm `AEAD_AES_256_GCM`, see rfc5116. The length of the `key` used for WeChat Pay is 32 bytes, the length of the random string `nonce` is 12 bytes, and the length of the `associated_data` is less than 16 bytes or may be zero.

4. Request Parameters

Name

Variable Name

Type

Required

Description

Notification ID

id

string[1,36]

Yes

The unique notification ID

Example: f7c34059-0f2d-5b32-ba33-a42dks0597c5

Notification creation time

create_time

string[1,64]

Yes

Notification creation time, in RFC3339 format

Example: 2018-06-08T10:34:56+08:00

Notification type

event_type

string[1,32]

Yes

Notification type:
REFUND.SUCCESS： Notification on a successful refund
REFUND.CLOSED：Notification on a closed refund

Example: REFUND.SUCCESS

Brief description of notice

summary

string[1,16]

Yes

Brief description of notice

Example value: refund succeeded

Notification data type

resource_type

string[1,32]

Yes

The type of the notification resource data. The type of resource data for the refund notification is encrypt-resource.Example: encrypt-resource

Notification data

resource

object

Yes

Resource data of a notification

Notification data

5. Notification Signature

Encryption does not guarantee that the notification request comes from wechat pay. Wechat pay will sign the notification sent to the merchant and put the signature value in the Wechatpay-Signature of Notification's HTTP header. The merchant should verify the signature to confirm that the request is from wechat pay, not other third parties. For the algorithm of signature verification, please refer to《Wechat Pay API V3 Signature Scheme》。

6. Notification example

Payment Success Result Notification

1{
2	"id": "f7c34059-0f2d-5b32-ba33-a42dks0597c5",
3	"create_time": "2018-06-08T10:34:56+08:00",
4	"resource_type": "encrypt-resource",
5	"event_type": "REFUND.SUCCESS",
6	"summary": "Refunded",
7	"resource": {
8		"original_type": "refund",
9		"algorithm": "AEAD_AES_256_GCM",
10		"ciphertext": "...",
11		"associated_data": "",
12		"nonce": "..."
13	}
14}

List of decrypted resource objects:

1{
2    "sp_mchid": "1900000100",
3    "sub_mchid": "1900000109",
4    "transaction_id": "1008450740201411110005820873",
5    "out_trade_no": "20150806125346",
6    "refund_id": "50200207182018070300011301001",
7    "out_refund_no": "7752501201407033233368018",
8    "refund_status": "SUCCESS",
9    "success_time": "2018-06-08T10:34:56+08:00",
10    "recv_account": "China Merchants Bank Credit Card 0403",
11    "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
12    "amount" : {
13        "total": 528800,
14        "currency": "HKD",
15        "refund": 528800,
16        "payer_total": 528800,
17        "payer_refund": 528800,
18        "payer_currency": "HKD",
19        "exchange_rate" : {
20            "type": "SETTLEMENT_RATE",
21            "rate": 100000000
22        }
23    }
24}

7. List of decrypted resource objects

Name

Variable Name

Type

Required

Description

Merchant ID

mchid

string[1,32]

Yes

Merchant ID assigned by WeChat Pay
Note: Only for Common mode
Example: 1900000109

Institution's Merchant ID

sp_mchid

string[1,32]

Yes

Institution's Merchant ID assigned by WeChat Pay

Note: Only for Institutional mode
Example: 1900000100

Sub-merchant ID

sub_mchid

string[1,32]

Yes

Merchant ID assigned to sub-merchants by WeChat Pay

Note: Only for Institutional mode
Example: 1900000109

Merchant order No.

out_trade_no

string[1,32]

Yes

Returned merchant's order No.

Example: 1217752501201407033233368018

WeChat Pay order No.

transaction_id

string[1,32]

Yes

WeChat Pay order No.

Example: 1217752501201407033233368018

Merchant refund No.

out_refund_no

string[1,64]

Yes

Merchant refund No.

Example: 1217752501201407033233368018

WeChat refund No.

refund_id

string[1,32]

Yes

WeChat refund No.

Example: 1217752501201407033233368018

Refund status

refund_status

string[1,16]

Yes

Refund status:
SUCCESS：Refund successful
CLOSED：Refund closed

Example: SUCCESS

Refund completion time

success_time

string[1,64]

No

Refund completion time, which is returned when the refund status is successful in RFC3339 format.Example: 2018-06-08T10:34:56+08:00

Refund receiving account

recv_account

string[1,64]

Yes

Refund receiving party of the current refund order
1）Refund to bank cards:
{Bank name}{Card type}{Last numbers of the bank card}
2） Refund to the balance of the paying user:
The balance of the paying user
3）Refund to the merchant:
Merchant's basic account
Merchant's settlement bank account
4）Refund to the Mini Fund of the paying user:
The Mini Fund of the paying user

Example: China Merchants Bank Credit Card 0403

Refund source

fund_source

string[1,30]

No

REFUND_SOURCE_UNSETTLED_FUNDS： Refund with unsettled funds (default)
REFUND_SOURCE_RECHARGE_FUNDS：Refund with available balance

Example: REFUND_SOURCE_UNSETTLED_FUNDS

Amount information

amount

object

Yes

Information on the amount. For more information, see the description below.

Amount information

8. Response Result

After the merchant's backend has properly processed the notification, HTTP status code 200 or 204 needs to be returned. No specific content is required for 204.For other HTTP status codes, WeChat Pay will deem the notification as a failure, and will send the notification regularly by following the aforesaid policies.

Notice

If the merchant's backend fails to process a response, WeChat Pay will record the response message. It is recommended to return in the following format.

Name	Variable Name	Type	Required	Description
Returned status code	code	string[1,32]	Yes	For more information, see the returned status code description below.Example: SUCCESS
Returned message	message	string[1,256]	No	Returned message, which presents the cause of the error. Example: System error

Name

Variable Name

Type

Required

Description

Returned status code

code

string[1,32]

Yes

For more information, see the returned status code description below.Example: SUCCESS

Returned message

message