Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Refund Application API

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.

Notes:

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.


API intro

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.

Request Parameters

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.
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(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 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

For example:


{
    "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"
}

    
{
JAVA示例代码
}
    

Response for successful request

Response for failed request

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
Location of the incorrect parameter field string(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.
Example:#/properties/payer
Value of the incorrect parameter value string(256) Yes Value of the incorrect parameter
Example:1346177081915535577
Cause of error issue string(256) Yes Cause of error
Example:It is different from ALLOF schema
Location of the incorrect parameter location string(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
Example:body

Response for successful request:

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.
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(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(16) Yes Three-letter code in accordance with ISO 4217.
Example:CNY
+ Exchange rate exchange_rate object  Yes Exchange rate information
Name Variable Name Type Required Description
Exchange rate type type string(16) No When the priced currency and the payment currency are the same, type="SETTLEMENT_RATE", i.e. the exchange rate between the [real-time] priced currency and the settlement currency.
When the priced currency and the payment currency are different, type="USERPAYMENT_RATE", i.e. the exchange rate between the [original payment] priced currency and the payment 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
+ Discount refund details detail array No Discount refund details. For more information, see the description below.
Name Variable Name Type Required Description
Voucher ID promotion_id string(32) Yes Voucher or discount ID
Example:109519
Discount range scope string(32) No GLOBAL:All-item voucher
SINGLE: Single-item discount
Example:SINGLE
Discount type type string(32) No 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(16) Yes Three-letter code in accordance with ISO 4217.
Example:CNY

For example:


{
	"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"
}
]
}
{
"code":"INVALID_REQUEST",
"message":"Parameter format verification error",
"detail":{
    "field":"#/properties/payer",
    "value":"1346177081915535577",
    "issue":"It is different from ALLOF schema",
    "location":"body"
   }
}

Error Codes

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.


Release notes

close
V1.0
2020.04.30
1. Refund Application API released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global