Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Submit Refund API

Latest update time:2019.11.20 Release notes


For a period after a payment transaction has been completed and a refund is required by either the Payer or Merchant, the Merchant can refund the Payer via this API. After the WeChat payment system receives and verifies the refund request successfully, the Payer will be refunded with the request refund amount (less than or equal to the original payment amount) according to the refund rules.

Tips:

1. Orders that have been completed for more than one year cannot be submitted for refund.

2. A refund for a transaction can be processed in the form of multiple partial refunds. In this case, the original order number is required and multiple refund numbers must be set. The total refund amount cannot exceed the original payment amount.

If the refund request is failed, please use the same out_refund_no for retrying.

1. Request frequency limit: 150qps, which means normal refund requests should be less than 150 times per secon.

2. Error or invalid request frequency limit: 6 qps, which means error or invalid refund requests should be less than 6 times per second.

partial refund for one order should be less than 50 times.

API intro

Request Url: https://api.mch.weixin.qq.com/secapi/pay/refund

Request Method: POST

Certificate Requirements: Two-way certificate is required.

Applicable Object: Common modeInstitutional mode

Parameter Settings

Name ID Type Required Description
Official Account ID appid String(32) Yes Specifies an Official Account ID assigned by WeChat
Example: wx8888888888888888
Merchant ID mch_id String(32) Yes Specifies merchant ID assigned by WeChat Payment
Example: 1900000109
Sub Official Account ID sub_appid String(32) No Specifies an Sub Official Account ID assigned by WeChat
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: wx8888888888888888
Sub  Merchant ID sub_mch_id String(32) Yes Specifies Sub merchant ID assigned by WeChat Payment
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: 1900000109
Random string nonce_str String(32) Yes 32 characters or fewer. For more information, see Random String Algorithm .
Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Signature sign String(64) Yes Specifies a signature. For more information, see Signature Algorithm.
Example: C380BEC2BFD727A4B6845133519F3AD6
Sign type sign_type String(32) No Currently HMAC-SHA256 and MD5 are supported, default is MD5. This parameter must be submitted if HMAC-SHA256 is chosen
Example: HMAC-SHA256/MD5
WeChat Order Number transaction_id String(32) Choose one to submit Specifies the WeChat payment order id number.

Example: 1217752501201407033233368018

Merchant Order Number out_trade_no String(32) out_trade_no is an internal order number within the merchant’s system.
transaction_id will be used over out_trade_no if they are both provided by the merchant.
Example: 1217752501201407033233368018
Merchant Refund Number out_refund_no String(32) Yes Specifies the internal refund number, which is unique in the system. A single transaction can be processed as multiple partial refunds, with the total sum of the partial refunds being equal to the original one.
Example: 1217752501201407033233368018
Total Amount total_fee int Yes Specifies the total order amount. The units are expressed in cents and must be an integer. For more information, see Payment Amount.
Example: 100
Refund Amount refund_fee int Yes Specifies the total refund amount for a transaction. The units are expressed in cents and shall be an integer.
Currency Type refund_fee_type String(8) No ISO-4217 standard compliant and be described by three characters based code. The refund currency type must be same with the bid currency type. For more information, see Currency Type.
Example: USD
Refund Reason refund_desc String(80) No It will inform the shoppers the refund reason once merchants submit this field value.
Example: Products sold out

Example:


  <xml>
     <return_code><![CDATA[SUCCESS]]></return_code>  
     <return_msg><![CDATA[OK]]></return_msg>
     <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
     <mch_id><![CDATA[10000100]]></mch_id>
     <sub_mch_id><![CDATA[452532745]]></sub_mch_id>
     <nonce_str><![CDATA[0ScvLJ2uasseqcoQ]]></nonce_str>
     <sign><![CDATA[2457A269C435031EB2F2E0EE531DABDD]]></sign>
     <result_code><![CDATA[SUCCESS]]></result_code>
     <transaction_id><![CDATA[4200001126202109090793359667]]></transaction_id>
     <out_trade_no><![CDATA[1678371718207313]]></out_trade_no>
     <out_refund_no><![CDATA[REF16001202]]></out_refund_no>
     <refund_id><![CDATA[50201409582021110313317567694]]></refund_id>
     <refund_channel><![CDATA[]]></refund_channel>
     <refund_fee>1</refund_fee>
     <coupon_refund_fee>0</coupon_refund_fee>
     <total_fee>1</total_fee>
     <cash_fee>7</cash_fee>
     <fee_type><![CDATA[EUR]]></fee_type>
     <coupon_refund_count>0</coupon_refund_count>
     <cash_refund_fee>7</cash_refund_fee>
     <refund_fee_type><![CDATA[EUR]]></refund_fee_type>
     <cash_fee_type><![CDATA[CNY]]></cash_fee_type>
     <cash_refund_fee_type><![CDATA[CNY]]></cash_refund_fee_type>
  </xml> 
  				

  <xml>
     <return_code><![CDATA[SUCCESS]]></return_code>  
     <return_msg><![CDATA[OK]]></return_msg>
     <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
     <mch_id><![CDATA[10000100]]></mch_id>
     <sub_mch_id><![CDATA[452532745]]></sub_mch_id>
     <nonce_str><![CDATA[3LyB9n5DeLnneJ1p]]></nonce_str>
     <sign><![CDATA[3DC2A09C6CB967088C85ADD64CCCBA0A]]></sign>
     <result_code><![CDATA[FAIL]]></result_code>
     <err_code><![CDATA[INVALID_REQUEST]]></err_code>
     <err_code_des><![CDATA[订单已全额退款]]></err_code_des>
  </xml> 
  				

  <xml>
   <return_code><![CDATA[SUCCESS]]></return_code>  
   <return_msg><![CDATA[OK]]></return_msg>
   <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
   <mch_id><![CDATA[10000100]]></mch_id>
   <sub_mch_id><![CDATA[440219171]]></sub_mch_id>
   <nonce_str><![CDATA[KUX981nx6iLew1UR]]></nonce_str>
   <sign><![CDATA[AEA3AEBCB295090718B3D3593D79853731014238BFFB432152DC8F8916F22749]]></sign>
   <result_code><![CDATA[FAIL]]></result_code>
   <err_code><![CDATA[NOTENOUGH]]></err_code>
   <err_code_des><![CDATA[交易未结算资金不足,请使用可用余额退款]]></err_code_des>
  </xml> 
  				
    
{
JAVA示例代码
}
    

Notes: Parameters are escaped in XML files and CDATA tags are used to illustrate that data is not parsed by XML parser.

Return Data

Name ID Type Required Description
Return Status Code return_code String(16) Yes Set to SUCCESS or FAIL
Specifies communicating label instead of transaction label. The status of the transaction is determined by the value of the result_code field.
Example:SUCCESS
Return Data return_msg String(128) No If not empty, this is the error description. If not empty, this is the error description
Signature Failure
Parameter format checking error
Example:Signature Failure

When return_code is SUCCESS, return data will also include the following fields:


Name ID Type Required Description
Result Code result_code String(16) Yes SUCCESS/FAIL
1. SUCCESS: Receives refund application successfully. To get refund status, calling Query Refund API is required.
2. FAIL: Submitting refund application failed.
Example: SUCCESS
Error Code err_code String(32) No For more information, please refer to error code list.
Example: SYSTEMERROR
Error Code Description err_code_des String(32) No Describes result data.
Example: System timed out
Official Account ID appid String(32) Yes The Official Account ID submitted when calling the interface
Example: wx8888888888888888
Merchant ID mch_id String(32) Yes The Merchant ID submitted when calling the interface
Example: 1900000109
Sub Official Account ID sub_appid String(32) No The Sub Official Account ID submitted when calling the interface
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: wx8888888888888888
Sub  Merchant ID sub_mch_id String(32) Yes The Sub Merchant ID submitted when calling the interface
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: 1900000109
Random String nonce_str String(32) Yes 32 characters or fewer
Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Signature sign String(64) Yes Specifies a signature. For more information, see Signature Algorithm
Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS
WeChat Order Number transaction_id String(32) Yes Specifies the WeChat payment order id
Example:1217752501201407033233368018
Merchant Order Number out_trade_no String(32) Yes Specifies the order number created within the Merchants' system, which is consistent with request.
Example:1217752501201407033233368018
Merchant Refund Number out_refund_no String(32) Yes

Merchant Refund Number.
Example: 1217752501201407033233368018

WeChat Refund Number refund_id String(32) Yes

WeChat Refund Number.
Example: 1217752501201407033233368018

Refund Amount refund_fee int Yes Specifies the total refund amount expressed in cents and must be an integer.
Example: 100
Currency Type refund_fee_type String(8) Yes

ISO-4217 standard compliant and be described by three characters based code. The refund currency type must be same with the bid currency type. For more information, see Section 4.2 Currency Type.
Example: USD

Total Amount total_fee int Yes Specifies the total amount for a transaction. The unit is cent and the value must be integer. For more information, see Payment Amount.
Example:100
Order Currency Type fee_type String(8) No ISO-4217 standard compliant and be described by three characters based code. For more information, see Currency Type.
Example: CNY
Cash Payment Amount cash_fee int Yes

Specifies the cash payment amount expressed in cents and must be an integer. For more information, see Payment Amount.
Example: 100

Currency Type cash_fee_type String(8) Yes

Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Section 4.2 Currency Type.
Example: CNY

Cash Refund Amount cash_refund_fee int Yes

Specifies the cash refund amount expressed in cents and must be an integer. For more information, see Payment Amount.
Example: 100

Cash Refund Currency Type cash_refund_fee_type String(8) No

Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Currency Type.
Example: CNY

Example:


<xml>
   <return_code><![CDATA[SUCCESS]]></return_code>
   <return_msg><![CDATA[OK]]></return_msg>
   <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
   <mch_id><![CDATA[10000100]]></mch_id>
   <nonce_str><![CDATA[NfsMFbUFpdbEhPXP]]></nonce_str>
   <sign><![CDATA[B7274EB9F8925EB93100DD2085FA56C0]]></sign>
   <result_code><![CDATA[SUCCESS]]></result_code>
   <transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
   <out_trade_no><![CDATA[1415757673]]></out_trade_no>
   <out_refund_no><![CDATA[1415701182]]></out_refund_no>
   <refund_id><![CDATA[2008450740201411110000174436]]></refund_id>
   <refund_fee>1</refund_fee>
   <cash_refund_fee_type><![CDATA[CNY]]></cash_refund_fee_type>
</xml> 

Error Codes

Name Description Reason Solution
SYSTEMERROR API return error System timed out Call this API again using the same parameters
BIZERR_NEED_RETRY internal error internal error caused by concurrency Please retry with the same parameter and do not change the out_refund_no
TRADE_OVERDUE Beyond refund period The longest refund period of one order is 365 days Please find another way to refund
ERROR Business error Business error when initiate refund The detailed reason will return
USER_ACCOUNT_ABNORMAL Refund request failed User’s account cancelled This error code means refund request failed, merchants need to handle the refund by themselves
INVALID_REQ_TOO_MUCH Invalid request count reaches the limit There are too much invalid requests Please check whether your system is working well
NOTENOUGH Not enough unsettled fund for refund There is not enough unsettled fund for refund This error code means refund request failed, merchants need to recall the refund API once there is enough unsettled fund, or retry it continuously
INVALID_TRANSACTIONID Invalid transaction_id Requested parameters are not correct Incorrect request parameters. Check whether the original transaction ID exists or whether data failed to be returned from the payment interface.
PARAM_ERROR Parameter error Requested parameters are not correct Incorrect request parameters. Check the parameters and call the Submit Refund API again.
APPID_NOT_EXIST APPID DOES NOT EXIST No APPID in this parameter Check whether the provided APPID is correct
MCHID_NOT_EXIST MCHID DOES NOT EXIST No MCHID in this parameter Check whether the provided MCHID is correct
APPID_MCHID_NOT_MATCH appid does not match mch_id appid does not match mch_id Check whether appid belongs to the associated mch_id
REQUIRE_POST_METHOD Use post method Data is not transferred by post Check whether data is submitted by POST method
SIGNERROR Signature error Incorrect signature result Check whether the signature parameter and method complies with signature algorithm requirements
XML_FORMAT_ERROR INVALID XML FORMAT INVALID XML FORMAT Check whether XML parameters are in the correct format

Release notes

关闭
V1.0
2019.11.20
1. Submit Refund 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