WeChat Pay Open Platform

1. API intro

Applicable object:Common modeInstitutional mode

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

Request method: POST

rate limitt:150qps

Pathparameter is a path parameter.

Queryparameter needs to be passed in the request URL.

Bodyparameter 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 forCommon 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 forCommon mode
Example: wx8888888888888888

Institution's Merchant ID

sp_mchid

string[1,32]

Yes

BodyMerchant ID assigned to institutions by WeChat Pay
Note: Only forInstitutional mode
Example: 1900000100

Sub-merchant ID

sub_mchid

string[1,32]

Yes

Body Merchant ID assigned to sub-merchants by WeChat Pay
Note: Only forInstitutional mode
Example: 1900000109

Organization APPID

sp_appid

string[1,32]

Yes

BodyAPPID 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[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 forInstitutional 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

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[1,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 Source & Amount

from

array

No

This parameter is used to specify the fund source and amount for cross-border funds-distribution orders.
If this parameter is not specified for a funds-distribution order, the refund will be made from the undistributed refundable balance of the order by default, and the shortfall will be made up by the advance refund amount.
The specific fund source and amount are subject to the "from" field in the response parameter.
This parameter applies to usage scenarios meeting the following conditions:
1. The order is a cross-border funds-distribution order. Do not specify this parameter for non-cross-border orders.
Parameter passing needs to meet the following conditions:
1. The sum of the fund amount from the advance refundable balance and the fund amount from the undistributed refundable balance of the order is equal to the refund amount;
2. The fund sources cannot be duplicated.
If any of the above conditions are not met, an error will be returned.

Name	Variable Name	Type	Required	Description
Fund Source	fund_source	string[1,32]	Yes	The source of the refund, which can be any of the enumerated values below. Enumerated values: FUNDS_REFUNDABLE_BALANCE : Advance refundable balance ORDER_REFUNDABLE_BALANCE : Undistributed refundable balance Example：ORDER_REFUNDABLE_BALANCE
Fund Amount	amount	int	Yes	The amount funded from a source, which can only be an integer in the smallest unit of currency. Example：888

pack up

Refund notification URL

notify_url

string[1,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

Request Eample

Scenario 1: Regular order refund requestScenario 2: Request for refund of designated funding source for split order


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


{
	"sp_appid": "wx7bc98d929da735fe",
	"sp_mchid": "999952224",
	"sub_mchid": "999968479",
	"out_trade_no": "20220724trade004",
	"out_refund_no": "20220724trade004refund001",
	"amount": {
		"currency": "CNY",
		"refund": 500,
		"total": 1000,
		"from": [{
				"fund_source": "FUNDS_REFUNDABLE_BALANCE",
				"amount": 200
			},
			{
				"fund_source": "ORDER_REFUNDABLE_BALANCE",
				"amount": 300
			}  //#Note: The sum of the funding source amounts must be equal to the total refund amount， just 200 + 300 = 500
		]
	},
	"reason": "The item has been sold out."
}

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.

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[1,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[1,16]

Yes

Three-letter code in accordance with ISO 4217.
Example: CNY

Settlement Currency Refund Amount

settlement_refund

int

Yes

The refund amount corresponding to the merchant's settlement currency, the smallest unit of the currency, which can only be an integer.
Example: 888

Settlement Currency

settlement_currency

string[1,16]

Yes

Settlement currency, a three-letter code that conforms to the ISO 4217 standard, see the currency type on the currency list.
Example: HKD

Exchange rate

exchange_rate

object

Yes

Exchange rate information

Name

Variable Name

Type

Required

Description

Exchange rate type

type

string[1,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

Refund Source & Amount

from

array

No

This parameter is used to specify the fund source and amount for cross-border funds-distribution orders.
If this parameter is not specified for a funds-distribution order, the refund will be made from the undistributed refundable balance of the order by default, and the shortfall will be made up by the advance refund amount.
The specific fund source and amount are subject to the "from" field in the response parameter.
This parameter applies to usage scenarios meeting the following conditions:
1. The order is a cross-border funds-distribution order. Do not specify this parameter for non-cross-border orders.
Parameter passing needs to meet the following conditions:
1. The sum of the fund amount from the advance refundable balance and the fund amount from the undistributed refundable balance of the order is equal to the refund amount;
2. The fund sources cannot be duplicated.
If any of the above conditions are not met, an error will be returned.

Name	Variable Name	Type	Required	Description
Fund Source	fund_source	string[1,32]	Yes	The source of the refund, which can be any of the enumerated values below. Enumerated values: FUNDS_REFUNDABLE_BALANCE : Advance refundable balance ORDER_REFUNDABLE_BALANCE : Undistributed refundable balance Example：ORDER_REFUNDABLE_BALANCE
Fund Amount	amount	int	Yes	The amount funded from a source, which can only be an integer in the smallest unit of currency. Example：888

pack up

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[1,32]	Yes	Voucher or discount ID Example: 109519
Discount range	scope	string[1,32]	No	GLOBAL：All-item voucher SINGLE： Single-item discount Example: SINGLE
Discount type	type	string[1,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[1,16]	Yes	Three-letter code in accordance with ISO 4217. Example: CNY

pack up

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.

Name	Variable Name	Type	Required	Description
The location of incorrect parameter	field	string[1,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.
Value of the incorrect parameter	value	string[1,256]	Yes	Value of the incorrect parameter
Cause of error	issue	string[1,256]	Yes	Cause of error
Location of the incorrect parameter	location	string[1,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

pack up

Response Example:

No Accounts Order Return Example Accounts Order Return Example Exception Example


{
    "id": "50202002642022072801898085012",
    "out_refund_no": "20220724trade003refund001",
    "create_time": "2022-07-28T15:44:07+08:00",
    "amount": {
        "refund": 500,
        "currency": "CNY",
        "payer_refund": 250,
        "payer_currency": "CNY",
        "settlement_refund": 578,
        "settlement_currency": "HKD",
        "exchange_rate": {
            "type": "SETTLEMENT_RATE",
            "rate": 86500000
        }
    },
    "detail": [
        {
            "promotion_id": "11006096615",
            "scope": "GLOBAL",
            "type": "COUPON",
            "amount": 500,
            "refund_amount": 250,
            "currency": "CNY"
        }
    ]
}


{
    "id": "50201702652022072801898085013",
    "out_refund_no": "20220724trade004refund001",
    "create_time": "2022-07-28T15:51:57+08:00",
    "amount": {
        "refund": 500,
        "currency": "CNY",
        "payer_refund": 250,
        "payer_currency": "CNY",
        "settlement_refund": 578,
        "settlement_currency": "HKD",
        "exchange_rate": {
            "type": "SETTLEMENT_RATE",
            "rate": 86490000
        },
        "from": [
            {
                "fund_source": "ORDER_REFUNDABLE_BALANCE",
                "amount": 300
            },
            {
                "fund_source": "FUNDS_REFUNDABLE_BALANCE",
                "amount": 200
            }
        ]
    },
    "detail": [
        {
            "promotion_id": "11006096908",
            "scope": "GLOBAL",
            "type": "COUPON",
            "amount": 500,
            "refund_amount": 250,
            "currency": "CNY"
        }
    ]
}


{
	"code": "INVALID_REQUEST",
	"message": "Parameter format verification error",
	"detail": {
		"field": "#/properties/payer",
		"value": "1346177081915535577",
		"issue": "Not in line with ALLOF schema",
		"location": "body"
	}
}

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.

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Payments

Funding Products

Other Products

Submit Refund API

1. API intro

2. Request Parameters

Request Eample

3. Response Parameters

Response for successful request:

Response for failed request:

Response Example:

4. Error Codes