WeChat Pay Open Platform

API intro

Request URL：https://api.mch.weixin.qq.com/hk/v3/refunds/id/{id}?sp_mchid=parameter value1&sub_mchid=parameter value2
OR
https://api.mch.weixin.qq.com/hk/v3/refunds/out-refund-no/{out_refund_ no}?sp_mchid=parameter value1&sub_mchid=parameter value2
Note: The {id} in the URL refers to the refund No. on WeChat, while the {out_refund_no} refers to the actual merchant refund No., either of which is called.For orders completed one year ago, check the refund via the merchant refund No.

Request method: GET

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	query Merchant ID assigned by WeChat Pay Note: Only forCommon mode Example：1900000109
Sub-merchant ID	sub_mchid	string(32)	Yes	query Merchant ID assigned to sub-merchants by WeChat Pay Note: Only forInstitutional mode Example：1900000109
Institution's Merchant ID	sp_mchid	string(32)	Yes	query Merchant ID assigned to merchants by WeChat Pay Note: Only forInstitutional mode Example：1900000100
WeChat Pay refund order No.	id	string(32)	Yes	path WeChat Pay refund order No. Example：1217752501201407033233368018
Merchant refund No.	out_refund_no	string(64)	Yes	path Returned refund order No. Example：1217752501201407033233368018

For example：

URL



https://api.mch.weixin.qq.com/hk/v3/refunds/id/1217752501201407033233368018?mchid=1900000109


https://api.mch.weixin.qq.com/hk/v3/refunds/out-refund-no/1217752501201407033233368018?sub_mchid=1900000109&sp_mchid=1900000100

    
｛
JAVA示例代码
｝

Returned Result

Response for successful 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

array

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

WeChat Pay transaction order No.

transaction_id

string(32)

Yes

WeChat Pay transaction order No.
Example：1217752501201407033233368018

Original merchant transaction order No.

out_trade_no

string(64)

Yes

The returned original transaction order No.
Example：1217752501201407033233368018

Refund channel

channel

string(16)

No

ORIGINAL：Refund to the paying account
BALANCE：Refund to the balance
OTHER_BALANCE：Refund to other balance accounts in case of original account error
OTHER_BANKCARD：Refund to other bank cards if there is something wrong with the original bank card.
Example：ORIGINAL

Refund receiving account

recv_account

string(64)

No

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 use:
The balance of the paying user
3）Refund to the Mini Fund of the paying user:
The Mini Fund of the paying use
Example：China Merchants Bank Credit Card 0403

Refund source

fund_source

string(30)

No

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

Refund completion time

success_time

string(64)

No

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

Refund creation time

create_time

string(64)

Yes

Refund acceptance time
Example：2018-06-08T10:34:56+08:00

Refund status

status

string(16)

Yes

Refund status:
SUCCESS：Refund successful
REFUNDCLOSE：Refund closed
PROCESSING：Refund in process
Example：SUCCESS

+ 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

Currency type

currency

string(16)

No

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 ratio is 1, then rate=100000000. If the exchange ratio is 6.5, then rate=650000000. Example：8000000

+ Discount refund details

detail

object

No

Discount refund info. 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",
    "transaction_id": "1008450740201411110005820873",
    "out_trade_no": "20150806125346",
    "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"
        }
    ],
    "channel": "ORIGINAL",
    "status": "SUCCESS",
    "recv_account": "China Merchants Bank Credit Card 0403",
    "fund_source": "REFUND_SOURCE_RECHARGE_FUNDS",
    "success_time": "2018-06-08T10:34:56+08:00",
    "create_time": "2018-06-08T10:34:56+08:00"
}

{
"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	Try call the API again.
REFUNDNOTEXIST	Failed to view the refund order	Check whether the order No. and the order status (e.g. unpaid and paid but not refunded) are correct. If there is no refund order under the order, only this error code is returned.
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	Request parameter was not properly filled in as instructed.	Invalid request parameter. Re-check the parameter 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.

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

QR Code Payment

Query Single Refund API

API intro

Request Parameters

For example：

Returned Result

Response for successful request

Response for successful request

For example：

Error Codes

Release notes