查询单笔退款(通过商户退款单号)
更新时间:2025.01.16提交退款申请后,推荐每间隔1分钟调用该接口查询一次退款状态,若超过5分钟仍是退款处理中状态,建议开始逐步衰减查询频率(比如之后间隔5分钟、10分钟、20分钟、30分钟……查询一次)。
退款有一定延时,零钱支付的订单退款一般5分钟内到账,银行卡支付的订单退款一般1-3个工作日到账。
同一服务商商户号查询退款频率限制为300qps,如返回FREQUENCY_LIMITED频率限制报错可间隔1分钟再重试查询。
接口说明
支持商户:【普通服务商】
请求方式:【GET】/v3/refund/domestic/refunds/{out_refund_no}
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
path 路径参数
out_refund_no 必填 string(64)
【商户退款单号】 服务商申请退款时传入的商户系统内部退款单号。
query 查询参数
sub_mchid 必填 string(32)
【子商户号(也叫特约商户号)】 服务商下单时传入的子商户号sub_mchid。
请求示例
需配合微信支付工具库 WXPayUtility 使用,请参考 Java
1package com.java.demo; 2 3import com.google.gson.annotations.Expose; 4import com.google.gson.annotations.SerializedName; 5import com.java.utils.WXPayUtility; // 引用微信支付工具库 参考:https://pay.weixin.qq.com/doc/v3/partner/4014985777 6import java.io.IOException; 7import java.io.UncheckedIOException; 8import java.security.PrivateKey; 9import java.security.PublicKey; 10import java.util.ArrayList; 11import java.util.HashMap; 12import java.util.List; 13import java.util.Map; 14import okhttp3.MediaType; 15import okhttp3.OkHttpClient; 16import okhttp3.Request; 17import okhttp3.RequestBody; 18import okhttp3.Response; 19 20/** 21 * 查询单笔退款(通过商户退款单号) 22 */ 23public class QueryByOutRefundNo { 24 private static String HOST = "https://api.mch.weixin.qq.com"; 25 private static String METHOD = "GET"; 26 private static String PATH = "/v3/refund/domestic/refunds/{out_refund_no}"; 27 28 public static void main(String[] args) { 29 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 30 QueryByOutRefundNo client = new QueryByOutRefundNo( 31 "填入 商户号", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 "填入 商户API证书序列号", // 商户API证书序列号,如何获取请参考https://pay.weixin.qq.com/doc/v3/partner/4013058924 33 "填入 商户API证书私钥文件路径", // 商户API证书私钥文件路径,本地文件路径 34 "填入 微信支付公钥ID", // 微信支付公钥ID,如何获取请参考https://pay.weixin.qq.com/doc/v3/partner/4013038589 35 "填入 微信支付公钥文件路径" // 微信支付公钥文件路径,本地文件路径 36 ); 37 38 QueryByOutRefundNoRequest request = new QueryByOutRefundNoRequest(); 39 request.outRefundNo = "1217752501201407033233368018"; 40 request.subMchid = "1900000109"; 41 try { 42 Refund response = client.run(request); 43 44 // TODO: 请求成功,继续业务逻辑 45 System.out.println(response); 46 } catch (WXPayUtility.ApiException e) { 47 // TODO: 请求失败,根据状态码执行不同的逻辑 48 e.printStackTrace(); 49 } 50 } 51 52 public Refund run(QueryByOutRefundNoRequest request) { 53 String uri = PATH; 54 uri = uri.replace("{out_refund_no}", WXPayUtility.urlEncode(request.outRefundNo)); 55 Map<String, Object> args = new HashMap<>(); 56 args.put("sub_mchid", request.subMchid); 57 uri = uri + "?" + WXPayUtility.urlEncode(args); 58 59 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 60 reqBuilder.addHeader("Accept", "application/json"); 61 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 62 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, null)); 63 reqBuilder.method(METHOD, null); 64 Request httpRequest = reqBuilder.build(); 65 66 // 发送HTTP请求 67 OkHttpClient client = new OkHttpClient.Builder().build(); 68 try (Response httpResponse = client.newCall(httpRequest).execute()) { 69 String respBody = WXPayUtility.extractBody(httpResponse); 70 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 71 // 2XX 成功,验证应答签名 72 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 73 httpResponse.headers(), respBody); 74 75 // 从HTTP应答报文构建返回数据 76 return WXPayUtility.fromJson(respBody, Refund.class); 77 } else { 78 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 79 } 80 } catch (IOException e) { 81 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 82 } 83 } 84 85 private final String mchid; 86 private final String certificateSerialNo; 87 private final PrivateKey privateKey; 88 private final String wechatPayPublicKeyId; 89 private final PublicKey wechatPayPublicKey; 90 91 public QueryByOutRefundNo(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 92 this.mchid = mchid; 93 this.certificateSerialNo = certificateSerialNo; 94 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 95 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 96 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 97 } 98 99 public enum Status { 100 @SerializedName("SUCCESS") 101 SUCCESS, 102 @SerializedName("CLOSED") 103 CLOSED, 104 @SerializedName("PROCESSING") 105 PROCESSING, 106 @SerializedName("ABNORMAL") 107 ABNORMAL 108 } 109 110 public enum Account { 111 @SerializedName("AVAILABLE") 112 AVAILABLE, 113 @SerializedName("UNAVAILABLE") 114 UNAVAILABLE 115 } 116 117 public enum PromotionType { 118 @SerializedName("COUPON") 119 COUPON, 120 @SerializedName("DISCOUNT") 121 DISCOUNT 122 } 123 124 public static class Refund { 125 @SerializedName("refund_id") 126 public String refundId; 127 128 @SerializedName("out_refund_no") 129 public String outRefundNo; 130 131 @SerializedName("transaction_id") 132 public String transactionId; 133 134 @SerializedName("out_trade_no") 135 public String outTradeNo; 136 137 @SerializedName("channel") 138 public Channel channel; 139 140 @SerializedName("user_received_account") 141 public String userReceivedAccount; 142 143 @SerializedName("success_time") 144 public String successTime; 145 146 @SerializedName("create_time") 147 public String createTime; 148 149 @SerializedName("status") 150 public Status status; 151 152 @SerializedName("funds_account") 153 public FundsAccount fundsAccount; 154 155 @SerializedName("amount") 156 public Amount amount; 157 158 @SerializedName("promotion_detail") 159 public List<Promotion> promotionDetail; 160 } 161 162 public static class GoodsDetail { 163 @SerializedName("merchant_goods_id") 164 public String merchantGoodsId; 165 166 @SerializedName("wechatpay_goods_id") 167 public String wechatpayGoodsId; 168 169 @SerializedName("goods_name") 170 public String goodsName; 171 172 @SerializedName("unit_price") 173 public Long unitPrice; 174 175 @SerializedName("refund_amount") 176 public Long refundAmount; 177 178 @SerializedName("refund_quantity") 179 public Integer refundQuantity; 180 } 181 182 public static class QueryByOutRefundNoRequest { 183 @SerializedName("out_refund_no") 184 @Expose(serialize = false) 185 public String outRefundNo; 186 187 @SerializedName("sub_mchid") 188 @Expose(serialize = false) 189 public String subMchid; 190 } 191 192 public enum Channel { 193 @SerializedName("ORIGINAL") 194 ORIGINAL, 195 @SerializedName("BALANCE") 196 BALANCE, 197 @SerializedName("OTHER_BALANCE") 198 OTHER_BALANCE, 199 @SerializedName("OTHER_BANKCARD") 200 OTHER_BANKCARD 201 } 202 203 public static class Amount { 204 @SerializedName("total") 205 public Long total; 206 207 @SerializedName("refund") 208 public Long refund; 209 210 @SerializedName("from") 211 public List<FundsFromItem> from; 212 213 @SerializedName("payer_total") 214 public Long payerTotal; 215 216 @SerializedName("payer_refund") 217 public Long payerRefund; 218 219 @SerializedName("settlement_refund") 220 public Long settlementRefund; 221 222 @SerializedName("settlement_total") 223 public Long settlementTotal; 224 225 @SerializedName("discount_refund") 226 public Long discountRefund; 227 228 @SerializedName("currency") 229 public String currency; 230 231 @SerializedName("refund_fee") 232 public Long refundFee; 233 } 234 235 public static class FundsFromItem { 236 @SerializedName("account") 237 public Account account; 238 239 @SerializedName("amount") 240 public Long amount; 241 } 242 243 public enum FundsAccount { 244 @SerializedName("UNSETTLED") 245 UNSETTLED, 246 @SerializedName("AVAILABLE") 247 AVAILABLE, 248 @SerializedName("UNAVAILABLE") 249 UNAVAILABLE, 250 @SerializedName("OPERATION") 251 OPERATION, 252 @SerializedName("BASIC") 253 BASIC, 254 @SerializedName("ECNY_BASIC") 255 ECNY_BASIC 256 } 257 258 public static class Promotion { 259 @SerializedName("promotion_id") 260 public String promotionId; 261 262 @SerializedName("scope") 263 public PromotionScope scope; 264 265 @SerializedName("type") 266 public PromotionType type; 267 268 @SerializedName("amount") 269 public Long amount; 270 271 @SerializedName("refund_amount") 272 public Long refundAmount; 273 274 @SerializedName("goods_detail") 275 public List<GoodsDetail> goodsDetail; 276 } 277 278 public enum PromotionScope { 279 @SerializedName("GLOBAL") 280 GLOBAL, 281 @SerializedName("SINGLE") 282 SINGLE 283 } 284}
需配合微信支付工具库 wxpay_utility 使用,请参考 Go
1package main 2 3import ( 4 "demo/wxpay_utility"// 引用微信支付工具库 参考:https://pay.weixin.qq.com/doc/v3/partner/4015119446 5 "encoding/json" 6 "fmt" 7 "net/http" 8 "net/url" 9 "strings" 10) 11 12func main() { 13 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 14 config, err := wxpay_utility.CreateMchConfig( 15 "填入 商户号", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考https://pay.weixin.qq.com/doc/v3/partner/4013080340 16 "填入 商户API证书序列号", // 商户API证书序列号,如何获取请参考https://pay.weixin.qq.com/doc/v3/partner/4013058924 17 "填入 商户API证书私钥文件路径", // 商户API证书私钥文件路径,本地文件路径 18 "填入 微信支付公钥ID", // 微信支付公钥ID,如何获取请参考https://pay.weixin.qq.com/doc/v3/partner/4013038589 19 "填入 微信支付公钥文件路径", // 微信支付公钥文件路径,本地文件路径 20 ) 21 if err != nil { 22 fmt.Println(err) 23 return 24 } 25 26 request := &QueryByOutRefundNoRequest{ 27 OutRefundNo: wxpay_utility.String("1217752501201407033233368018"), 28 SubMchid: wxpay_utility.String("1900000109"), 29 } 30 31 response, err := QueryByOutRefundNo(config, request) 32 if err != nil { 33 fmt.Printf("请求失败: %+v\n", err) 34 // TODO: 请求失败,根据状态码执行不同的处理 35 return 36 } 37 38 // TODO: 请求成功,继续业务逻辑 39 fmt.Printf("请求成功: %+v\n", response) 40} 41 42func QueryByOutRefundNo(config *wxpay_utility.MchConfig, request *QueryByOutRefundNoRequest) (response *Refund, err error) { 43 const ( 44 host = "https://api.mch.weixin.qq.com" 45 method = "GET" 46 path = "/v3/refund/domestic/refunds/{out_refund_no}" 47 ) 48 49 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 50 if err != nil { 51 return nil, err 52 } 53 reqUrl.Path = strings.Replace(reqUrl.Path, "{out_refund_no}", url.PathEscape(*request.OutRefundNo), -1) 54 query := reqUrl.Query() 55 query.Add("sub_mchid", *request.SubMchid) 56 reqUrl.RawQuery = query.Encode() 57 httpRequest, err := http.NewRequest(method, reqUrl.String(), nil) 58 if err != nil { 59 return nil, err 60 } 61 httpRequest.Header.Set("Accept", "application/json") 62 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 63 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), nil) 64 if err != nil { 65 return nil, err 66 } 67 httpRequest.Header.Set("Authorization", authorization) 68 69 client := &http.Client{} 70 httpResponse, err := client.Do(httpRequest) 71 if err != nil { 72 return nil, err 73 } 74 75 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 76 if err != nil { 77 return nil, err 78 } 79 80 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 81 // 2XX 成功,验证应答签名 82 err = wxpay_utility.ValidateResponse( 83 config.WechatPayPublicKeyId(), 84 config.WechatPayPublicKey(), 85 &httpResponse.Header, 86 respBody, 87 ) 88 if err != nil { 89 return nil, err 90 } 91 92 if err := json.Unmarshal(respBody, response); err != nil { 93 return nil, err 94 } 95 96 return response, nil 97 } else { 98 return nil, &wxpay_utility.ApiException{ 99 StatusCode: httpResponse.StatusCode, 100 Header: httpResponse.Header, 101 Body: respBody, 102 } 103 } 104} 105 106type Status string 107 108func (e Status) Ptr() *Status { 109 return &e 110} 111 112const ( 113 STATUS_SUCCESS Status = "SUCCESS" 114 STATUS_CLOSED Status = "CLOSED" 115 STATUS_PROCESSING Status = "PROCESSING" 116 STATUS_ABNORMAL Status = "ABNORMAL" 117) 118 119type Account string 120 121func (e Account) Ptr() *Account { 122 return &e 123} 124 125const ( 126 ACCOUNT_AVAILABLE Account = "AVAILABLE" 127 ACCOUNT_UNAVAILABLE Account = "UNAVAILABLE" 128) 129 130type PromotionType string 131 132func (e PromotionType) Ptr() *PromotionType { 133 return &e 134} 135 136const ( 137 PROMOTIONTYPE_COUPON PromotionType = "COUPON" 138 PROMOTIONTYPE_DISCOUNT PromotionType = "DISCOUNT" 139) 140 141type Refund struct { 142 RefundId *string `json:"refund_id,omitempty"` 143 OutRefundNo *string `json:"out_refund_no,omitempty"` 144 TransactionId *string `json:"transaction_id,omitempty"` 145 OutTradeNo *string `json:"out_trade_no,omitempty"` 146 Channel *Channel `json:"channel,omitempty"` 147 UserReceivedAccount *string `json:"user_received_account,omitempty"` 148 SuccessTime *string `json:"success_time,omitempty"` 149 CreateTime *string `json:"create_time,omitempty"` 150 Status *Status `json:"status,omitempty"` 151 FundsAccount *FundsAccount `json:"funds_account,omitempty"` 152 Amount *Amount `json:"amount,omitempty"` 153 PromotionDetail []Promotion `json:"promotion_detail,omitempty"` 154} 155 156type GoodsDetail struct { 157 MerchantGoodsId *string `json:"merchant_goods_id,omitempty"` 158 WechatpayGoodsId *string `json:"wechatpay_goods_id,omitempty"` 159 GoodsName *string `json:"goods_name,omitempty"` 160 UnitPrice *int64 `json:"unit_price,omitempty"` 161 RefundAmount *int64 `json:"refund_amount,omitempty"` 162 RefundQuantity *int64 `json:"refund_quantity,omitempty"` 163} 164 165type QueryByOutRefundNoRequest struct { 166 OutRefundNo *string `json:"out_refund_no,omitempty"` 167 SubMchid *string `json:"sub_mchid,omitempty"` 168} 169 170func (o *QueryByOutRefundNoRequest) MarshalJSON() ([]byte, error) { 171 type Alias QueryByOutRefundNoRequest 172 a := &struct { 173 OutRefundNo *string `json:"out_refund_no,omitempty"` 174 SubMchid *string `json:"sub_mchid,omitempty"` 175 *Alias 176 }{ 177 // 序列化时移除非 Body 字段 178 OutRefundNo: nil, 179 SubMchid: nil, 180 Alias: (*Alias)(o), 181 } 182 return json.Marshal(a) 183} 184 185type Channel string 186 187func (e Channel) Ptr() *Channel { 188 return &e 189} 190 191const ( 192 CHANNEL_ORIGINAL Channel = "ORIGINAL" 193 CHANNEL_BALANCE Channel = "BALANCE" 194 CHANNEL_OTHER_BALANCE Channel = "OTHER_BALANCE" 195 CHANNEL_OTHER_BANKCARD Channel = "OTHER_BANKCARD" 196) 197 198type Amount struct { 199 Total *int64 `json:"total,omitempty"` 200 Refund *int64 `json:"refund,omitempty"` 201 From []FundsFromItem `json:"from,omitempty"` 202 PayerTotal *int64 `json:"payer_total,omitempty"` 203 PayerRefund *int64 `json:"payer_refund,omitempty"` 204 SettlementRefund *int64 `json:"settlement_refund,omitempty"` 205 SettlementTotal *int64 `json:"settlement_total,omitempty"` 206 DiscountRefund *int64 `json:"discount_refund,omitempty"` 207 Currency *string `json:"currency,omitempty"` 208 RefundFee *int64 `json:"refund_fee,omitempty"` 209} 210 211type FundsFromItem struct { 212 Account *Account `json:"account,omitempty"` 213 Amount *int64 `json:"amount,omitempty"` 214} 215 216type FundsAccount string 217 218func (e FundsAccount) Ptr() *FundsAccount { 219 return &e 220} 221 222const ( 223 FUNDSACCOUNT_UNSETTLED FundsAccount = "UNSETTLED" 224 FUNDSACCOUNT_AVAILABLE FundsAccount = "AVAILABLE" 225 FUNDSACCOUNT_UNAVAILABLE FundsAccount = "UNAVAILABLE" 226 FUNDSACCOUNT_OPERATION FundsAccount = "OPERATION" 227 FUNDSACCOUNT_BASIC FundsAccount = "BASIC" 228 FUNDSACCOUNT_ECNY_BASIC FundsAccount = "ECNY_BASIC" 229) 230 231type Promotion struct { 232 PromotionId *string `json:"promotion_id,omitempty"` 233 Scope *PromotionScope `json:"scope,omitempty"` 234 Type *PromotionType `json:"type,omitempty"` 235 Amount *int64 `json:"amount,omitempty"` 236 RefundAmount *int64 `json:"refund_amount,omitempty"` 237 GoodsDetail []GoodsDetail `json:"goods_detail,omitempty"` 238} 239 240type PromotionScope string 241 242func (e PromotionScope) Ptr() *PromotionScope { 243 return &e 244} 245 246const ( 247 PROMOTIONSCOPE_GLOBAL PromotionScope = "GLOBAL" 248 PROMOTIONSCOPE_SINGLE PromotionScope = "SINGLE" 249)
GET
1curl -X GET \ 2 https://api.mch.weixin.qq.com/v3/refund/domestic/refunds/1217752501201407033233368018?sub_mchid=1900000109 \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" 5
应答参数
|
refund_id 必填 string(32)
【微信支付退款单号】申请退款受理成功时,该笔退款单在微信支付侧生成的唯一标识。
out_refund_no 必填 string(64)
【商户退款单号】 服务商申请退款时传入的商户系统内部退款单号。
transaction_id 必填 string(32)
【微信支付订单号】微信支付侧订单的唯一标识。
out_trade_no 必填 string(32)
【商户订单号】 服务商下单时传入的服务商系统内部订单号。
channel 必填 string
【退款渠道】 订单退款渠道
以下枚举:
ORIGINAL
: 原路退款BALANCE
: 退回到余额OTHER_BALANCE
: 原账户异常退到其他余额账户OTHER_BANKCARD
: 原银行卡异常退到其他银行卡(发起异常退款成功后返回)
user_received_account 必填 string(64)
【退款入账账户】 取当前退款单的退款入账方,有以下几种情况:
1)退回银行卡:{银行名称}{卡类型}{卡尾号}
2)退回支付用户零钱:支付用户零钱
3)退还商户:商户基本账户商户结算银行账户
4)退回支付用户零钱通:支付用户零钱通
5)退回支付用户银行电子账户:支付用户银行电子账户
6)退回支付用户零花钱:支付用户零花钱
7)退回用户经营账户:用户经营账户
8)退回支付用户来华零钱包:支付用户来华零钱包
9)退回企业支付商户:企业支付商户
success_time 选填 string(64)
【退款成功时间】
1、定义:退款成功的时间,该字段在退款状态status为SUCCESS(退款成功)时返回。
2、格式:遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE
。yyyy-MM-DD
表示年月日;T
字符用于分隔日期和时间部分;HH:mm:ss
表示具体的时分秒;TIMEZONE
表示时区(例如,+08:00
对应东八区时间,即北京时间)。
示例:2015-05-20T13:29:35+08:00
表示北京时间2015年5月20日13点29分35秒。
create_time 必填 string(64)
【退款创建时间】
1、定义:提交退款申请成功,微信受理退款申请单的时间。
2、格式:遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE
。yyyy-MM-DD
表示年月日;T
字符用于分隔日期和时间部分;HH:mm:ss
表示具体的时分秒;TIMEZONE
表示时区(例如,+08:00
对应东八区时间,即北京时间)。
示例:2015-05-20T13:29:35+08:00
表示北京时间2015年5月20日13点29分35秒。
status 必填 string
【退款状态】退款单的退款处理状态。
SUCCESS
: 退款成功CLOSED
: 退款关闭PROCESSING
: 退款处理中ABNORMAL
: 退款异常,退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往服务商平台-交易中心,手动处理此笔退款,可参考: 退款异常的处理,或者通过发起异常退款接口进行处理。
注:状态流转说明请参考状态流转图
funds_account 必填 string
【资金账户】 退款所使用资金对应的资金账户类型
UNSETTLED
: 未结算资金AVAILABLE
: 可用余额UNAVAILABLE
: 不可用余额OPERATION
: 运营账户BASIC
: 基本账户(含可用余额和不可用余额)ECNY_BASIC
: 数字人民币基本账户
amount 必填 object
【金额信息】订单退款金额信息
属性 | |||||
total 必填 integer 【订单金额】 订单总金额,单位为分 refund 必填 integer 【退款金额】退款金额,单位为分,只能为整数,可以做部分退款,不能超过原订单支付金额。 from 选填 array[object] 【退款出资账户及金额】 退款出资的账户类型及金额信息,若此接口请求时未传该参数,则不会返回。
payer_total 必填 integer 【用户实际支付金额】用户现金支付金额,整型,单位为分,例如10元订单用户使用了2元全场代金券,则该金额为用户实际支付的8元。 payer_refund 必填 integer 【用户退款金额】 指用户实际收到的现金退款金额,数据类型为整型,单位为分。例如在一个10元的订单中,用户使用了2元的全场代金券,若商户申请退款5元,则用户将收到4元的现金退款(即该字段所示金额)和1元的代金券退款。 settlement_refund 必填 integer 【应结退款金额】 去掉免充值代金券退款金额后的退款金额,整型,单位为分,例如10元订单用户使用了2元全场代金券(一张免充值1元 + 一张预充值1元),商户申请退款5元,则该金额为 退款金额5元 - 0.5元免充值代金券退款金额 = 4.5元。 settlement_total 必填 integer 【应结订单金额】去除免充值代金券金额后的订单金额,整型,单位为分,例如10元订单用户使用了2元全场代金券(一张免充值1元 + 一张预充值1元),则该金额为 订单金额10元 - 免充值代金券金额1元 = 9元。 discount_refund 必填 integer 【优惠退款金额】 申请退款后用户收到的代金券退款金额,整型,单位为分,例如10元订单用户使用了2元全场代金券,商户申请退款5元,用户收到的是4元现金 + 1元代金券退款金额(该字段) 。 currency 必填 string(16) 【退款币种】 固定返回:CNY,代表人民币。 refund_fee 选填 integer 【手续费退款金额】 订单退款时退还的手续费金额,整型,单位为分,例如一笔100元的订单收了0.6元手续费,商户申请退款50元,该金额为等比退还的0.3元手续费。 |
promotion_detail 选填 array[object]
【优惠退款详情】 订单各个代金券的退款详情,订单使用了代金券且代金券发生退款时返回。
属性 | |||||
promotion_id 必填 string(32) 【券ID】代金券id,单张代金券的编号 scope 必填 string 【优惠范围】优惠活动中代金券的适用范围,分为两种类型: type 必填 string 【优惠类型】代金券资金类型,优惠活动中代金券的结算资金类型,分为两种类型: amount 必填 integer 【优惠券面额】 代金券优惠的金额 refund_amount 必填 integer 【优惠退款金额】 代金券退款的金额 goods_detail 选填 array[object] 【退款商品】 指定商品退款时传的退款商品信息。
|
应答示例
200 OK
1{ 2 "refund_id" : "50000000382019052709732678859", 3 "out_refund_no" : "1217752501201407033233368018", 4 "transaction_id" : "1217752501201407033233368018", 5 "out_trade_no" : "1217752501201407033233368018", 6 "channel" : "ORIGINAL", 7 "user_received_account" : "招商银行信用卡0403", 8 "success_time" : "2020-12-01T16:18:12+08:00", 9 "create_time" : "2020-12-01T16:18:12+08:00", 10 "status" : "SUCCESS", 11 "funds_account" : "UNSETTLED", 12 "amount" : { 13 "total" : 100, 14 "refund" : 100, 15 "from" : [ 16 { 17 "account" : "AVAILABLE", 18 "amount" : 444 19 } 20 ], 21 "payer_total" : 90, 22 "payer_refund" : 90, 23 "settlement_refund" : 100, 24 "settlement_total" : 100, 25 "discount_refund" : 10, 26 "currency" : "CNY", 27 "refund_fee" : 100 28 }, 29 "promotion_detail" : [ 30 { 31 "promotion_id" : "109519", 32 "scope" : "GLOBAL", 33 "type" : "COUPON", 34 "amount" : 5, 35 "refund_amount" : 100, 36 "goods_detail" : [ 37 { 38 "merchant_goods_id" : "1217752501201407033233368018", 39 "wechatpay_goods_id" : "1001", 40 "goods_name" : "iPhone6s 16G", 41 "unit_price" : 528800, 42 "refund_amount" : 528800, 43 "refund_quantity" : 1 44 } 45 ] 46 } 47 ] 48}
错误码
公共错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
业务错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
401 | SIGN_ERROR | 签名错误 | 请检查签名参数和方法是否都符合签名算法要求,参考:如何生成签名 |
404 | MCH_NOT_EXISTS | MCHID不存在 | 请检查商户号是否正确,商户号获取方式请参考服务商模式开发必要参数说明 |
404 | RESOURCE_NOT_EXISTS | 退款单不存在 | 请检查商户退款单号是否有误以及订单状态是否正确,如:未支付 |
500 | SYSTEM_ERROR | 系统超时 | 请不要更换商户退款单号,请使用相同参数再次调用API。 |