发起异常退款
更新时间:2024.12.30提交退款申请后,退款结果通知或查询退款确认状态为退款异常,可调用此接口发起异常退款处理。支持退款至用户、退款至交易商户银行账户两种处理方式。
|
接口说明
支持商户:【普通商户】
请求方式:【POST】/v3/refund/domestic/refunds/{refund_id}/apply-abnormal-refund
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为application/json
path 路径参数
refund_id 必填 string(32)
【微信支付退款单号】申请退款受理成功时,该笔退款单在微信支付侧生成的唯一标识。申请退款成功后会返回该参数,查询退款或者退款结果通知也会返回该参数。
body 包体参数
out_refund_no 必填 string(64)
【商户退款单号】商户申请退款时传入的商户系统内部退款单号。
type 必填 string
【异常退款处理方式】 可选:退款至用户银行卡、退款至交易商户银行账户
可选取值
USER_BANK_CARD
: 退款到用户银行卡MERCHANT_BANK_CARD
: 退款至交易商户银行账户
bank_type 选填 string(16)
【开户银行】 银行类型,采用字符串类型的银行标识,值列表详见银行类型。仅支持招行、交通银行、农行、建行、工商、中行、平安、浦发、中信、光大、民生、兴业、广发、邮储、宁波银行的借记卡。
若退款至用户此字段必填。
bank_account 选填 string(1024)
【收款银行卡号】用户的银行卡账号,该字段需要使用微信支付公钥加密(推荐),请参考获取微信支付公钥ID说明以及如何使用微信支付公钥加密敏感字段,也可以使用微信支付平台证书公钥加密,参考平台证书简介与使用说明、如何使用平台证书加密敏感字段
若退款至用户此字段必填。
real_name 选填 string(1024)
【收款用户姓名】 收款用户姓名,该字段需要使用微信支付公钥加密(推荐),请参考获取微信支付公钥ID说明以及如何使用微信支付公钥加密敏感字段,也可以使用微信支付平台证书公钥加密,参考平台证书简介与使用说明、如何使用平台证书加密敏感字段
若退款至用户此字段必填。
请求示例
需配合微信支付工具库 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/merchant/4014931831 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 CreateAbnormalRefund { 24 private static String HOST = "https://api.mch.weixin.qq.com"; 25 private static String METHOD = "POST"; 26 private static String PATH = "/v3/refund/domestic/refunds/{refund_id}/apply-abnormal-refund"; 27 28 public static void main(String[] args) { 29 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/merchant/4013070756 30 CreateAbnormalRefund client = new CreateAbnormalRefund( 31 "填入 商户号", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考https://pay.weixin.qq.com/doc/v3/merchant/4013070756 32 "填入 商户API证书序列号", // 商户API证书序列号,如何获取请参考https://pay.weixin.qq.com/doc/v3/merchant/4013053053 33 "填入 商户API证书私钥文件路径", // 商户API证书私钥文件路径,本地文件路径 34 "填入 微信支付公钥ID", // 微信支付公钥ID,如何获取请参考https://pay.weixin.qq.com/doc/v3/merchant/4013038816 35 "填入 微信支付公钥文件路径" // 微信支付公钥文件路径,本地文件路径 36 ); 37 38 CreateAbnormalRefundRequest request = new CreateAbnormalRefundRequest(); 39 request.refundId = "50000000382019052709732678859"; 40 request.outRefundNo = "1217752501201407033233368018"; 41 request.type = AbnormalReceiveType.USER_BANK_CARD; 42 request.bankType = "ICBC_DEBIT"; 43 request.bankAccount = client.encrypt("bank_account"); 44 request.realName = client.encrypt("real_name"); 45 try { 46 Refund response = client.run(request); 47 48 // TODO: 请求成功,继续业务逻辑 49 System.out.println(response); 50 } catch (WXPayUtility.ApiException e) { 51 // TODO: 请求失败,根据状态码执行不同的逻辑 52 e.printStackTrace(); 53 } 54 } 55 56 public Refund run(CreateAbnormalRefundRequest request) { 57 String uri = PATH; 58 uri = uri.replace("{refund_id}", WXPayUtility.urlEncode(request.refundId)); 59 String reqBody = WXPayUtility.toJson(request); 60 61 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 62 reqBuilder.addHeader("Accept", "application/json"); 63 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 64 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, reqBody)); 65 reqBuilder.addHeader("Content-Type", "application/json"); 66 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 67 reqBuilder.method(METHOD, requestBody); 68 Request httpRequest = reqBuilder.build(); 69 70 // 发送HTTP请求 71 OkHttpClient client = new OkHttpClient.Builder().build(); 72 try (Response httpResponse = client.newCall(httpRequest).execute()) { 73 String respBody = WXPayUtility.extractBody(httpResponse); 74 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 75 // 2XX 成功,验证应答签名 76 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 77 httpResponse.headers(), respBody); 78 79 // 从HTTP应答报文构建返回数据 80 return WXPayUtility.fromJson(respBody, Refund.class); 81 } else { 82 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 83 } 84 } catch (IOException e) { 85 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 86 } 87 } 88 89 private final String mchid; 90 private final String certificateSerialNo; 91 private final PrivateKey privateKey; 92 private final String wechatPayPublicKeyId; 93 private final PublicKey wechatPayPublicKey; 94 95 public CreateAbnormalRefund(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 96 this.mchid = mchid; 97 this.certificateSerialNo = certificateSerialNo; 98 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 99 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 100 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 101 } 102 103 public String encrypt(String plainText) { 104 return WXPayUtility.encrypt(this.wechatPayPublicKey, plainText); 105 } 106 107 public enum Status { 108 @SerializedName("SUCCESS") 109 SUCCESS, 110 @SerializedName("CLOSED") 111 CLOSED, 112 @SerializedName("PROCESSING") 113 PROCESSING, 114 @SerializedName("ABNORMAL") 115 ABNORMAL 116 } 117 118 public enum Account { 119 @SerializedName("AVAILABLE") 120 AVAILABLE, 121 @SerializedName("UNAVAILABLE") 122 UNAVAILABLE 123 } 124 125 public enum PromotionType { 126 @SerializedName("COUPON") 127 COUPON, 128 @SerializedName("DISCOUNT") 129 DISCOUNT 130 } 131 132 public static class GoodsDetail { 133 @SerializedName("merchant_goods_id") 134 public String merchantGoodsId; 135 136 @SerializedName("wechatpay_goods_id") 137 public String wechatpayGoodsId; 138 139 @SerializedName("goods_name") 140 public String goodsName; 141 142 @SerializedName("unit_price") 143 public Long unitPrice; 144 145 @SerializedName("refund_amount") 146 public Long refundAmount; 147 148 @SerializedName("refund_quantity") 149 public Integer refundQuantity; 150 } 151 152 public enum Channel { 153 @SerializedName("ORIGINAL") 154 ORIGINAL, 155 @SerializedName("BALANCE") 156 BALANCE, 157 @SerializedName("OTHER_BALANCE") 158 OTHER_BALANCE, 159 @SerializedName("OTHER_BANKCARD") 160 OTHER_BANKCARD 161 } 162 163 public static class Amount { 164 @SerializedName("total") 165 public Long total; 166 167 @SerializedName("refund") 168 public Long refund; 169 170 @SerializedName("from") 171 public List<FundsFromItem> from; 172 173 @SerializedName("payer_total") 174 public Long payerTotal; 175 176 @SerializedName("payer_refund") 177 public Long payerRefund; 178 179 @SerializedName("settlement_refund") 180 public Long settlementRefund; 181 182 @SerializedName("settlement_total") 183 public Long settlementTotal; 184 185 @SerializedName("discount_refund") 186 public Long discountRefund; 187 188 @SerializedName("currency") 189 public String currency; 190 191 @SerializedName("refund_fee") 192 public Long refundFee; 193 } 194 195 public enum AbnormalReceiveType { 196 @SerializedName("USER_BANK_CARD") 197 USER_BANK_CARD, 198 @SerializedName("MERCHANT_BANK_CARD") 199 MERCHANT_BANK_CARD 200 } 201 202 public enum FundsAccount { 203 @SerializedName("UNSETTLED") 204 UNSETTLED, 205 @SerializedName("AVAILABLE") 206 AVAILABLE, 207 @SerializedName("UNAVAILABLE") 208 UNAVAILABLE, 209 @SerializedName("OPERATION") 210 OPERATION, 211 @SerializedName("BASIC") 212 BASIC, 213 @SerializedName("ECNY_BASIC") 214 ECNY_BASIC 215 } 216 217 public static class CreateAbnormalRefundRequest { 218 @SerializedName("refund_id") 219 @Expose(serialize = false) 220 public String refundId; 221 222 @SerializedName("out_refund_no") 223 public String outRefundNo; 224 225 @SerializedName("type") 226 public AbnormalReceiveType type; 227 228 @SerializedName("bank_type") 229 public String bankType; 230 231 @SerializedName("bank_account") 232 public String bankAccount; 233 234 @SerializedName("real_name") 235 public String realName; 236 } 237 238 public static class Promotion { 239 @SerializedName("promotion_id") 240 public String promotionId; 241 242 @SerializedName("scope") 243 public PromotionScope scope; 244 245 @SerializedName("type") 246 public PromotionType type; 247 248 @SerializedName("amount") 249 public Long amount; 250 251 @SerializedName("refund_amount") 252 public Long refundAmount; 253 254 @SerializedName("goods_detail") 255 public List<GoodsDetail> goodsDetail; 256 } 257 258 public static class Refund { 259 @SerializedName("refund_id") 260 public String refundId; 261 262 @SerializedName("out_refund_no") 263 public String outRefundNo; 264 265 @SerializedName("transaction_id") 266 public String transactionId; 267 268 @SerializedName("out_trade_no") 269 public String outTradeNo; 270 271 @SerializedName("channel") 272 public Channel channel; 273 274 @SerializedName("user_received_account") 275 public String userReceivedAccount; 276 277 @SerializedName("success_time") 278 public String successTime; 279 280 @SerializedName("create_time") 281 public String createTime; 282 283 @SerializedName("status") 284 public Status status; 285 286 @SerializedName("funds_account") 287 public FundsAccount fundsAccount; 288 289 @SerializedName("amount") 290 public Amount amount; 291 292 @SerializedName("promotion_detail") 293 public List<Promotion> promotionDetail; 294 } 295 296 public static class FundsFromItem { 297 @SerializedName("account") 298 public Account account; 299 300 @SerializedName("amount") 301 public Long amount; 302 } 303 304 public enum PromotionScope { 305 @SerializedName("GLOBAL") 306 GLOBAL, 307 @SerializedName("SINGLE") 308 SINGLE 309 } 310}
需配合微信支付工具库 wxpay_utility 使用,请参考 Go
1package main 2 3import ( 4 "bytes" 5 "demo/wxpay_utility"// 引用微信支付工具库 参考:https://pay.weixin.qq.com/doc/v3/merchant/4015119334 6 "encoding/json" 7 "fmt" 8 "net/http" 9 "net/url" 10 "strings" 11) 12 13func main() { 14 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/merchant/4013070756 15 config, err := wxpay_utility.CreateMchConfig( 16 "填入 商户号", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考https://pay.weixin.qq.com/doc/v3/merchant/4013070756 17 "填入 商户API证书序列号", // 商户API证书序列号,如何获取请参考https://pay.weixin.qq.com/doc/v3/merchant/4013053053 18 "填入 商户API证书私钥文件路径", // 商户API证书私钥文件路径,本地文件路径 19 "填入 微信支付公钥ID", // 微信支付公钥ID,如何获取请参考https://pay.weixin.qq.com/doc/v3/merchant/4013038816 20 "填入 微信支付公钥文件路径", // 微信支付公钥文件路径,本地文件路径 21 ) 22 if err != nil { 23 fmt.Println(err) 24 return 25 } 26 27 request := &CreateAbnormalRefundRequest{ 28 RefundId: wxpay_utility.String("50000000382019052709732678859"), 29 OutRefundNo: wxpay_utility.String("1217752501201407033233368018"), 30 Type: ABNORMALRECEIVETYPE_USER_BANK_CARD.Ptr(), 31 BankType: wxpay_utility.String("ICBC_DEBIT"), 32 BankAccount: wxpay_utility.String("d+xT+MQCvrLHUVDWv/8MR/dB7TkXLVfSrUxMPZy6jWWYzpRrEEaYQE8ZRGYoeorwC+w=="), /*请传入 wxpay_utility.EncryptOAEPWithPublicKey 加密结果*/ 33 RealName: wxpay_utility.String("UPgQcZSdq3zOayJwZ5XLrHY2dZU1W2Cd"), /*请传入 wxpay_utility.EncryptOAEPWithPublicKey 加密结果*/ 34 } 35 36 response, err := CreateAbnormalRefund(config, request) 37 if err != nil { 38 fmt.Printf("请求失败: %+v\n", err) 39 // TODO: 请求失败,根据状态码执行不同的处理 40 return 41 } 42 43 // TODO: 请求成功,继续业务逻辑 44 fmt.Printf("请求成功: %+v\n", response) 45} 46 47func CreateAbnormalRefund(config *wxpay_utility.MchConfig, request *CreateAbnormalRefundRequest) (response *Refund, err error) { 48 const ( 49 host = "https://api.mch.weixin.qq.com" 50 method = "POST" 51 path = "/v3/refund/domestic/refunds/{refund_id}/apply-abnormal-refund" 52 ) 53 54 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 55 if err != nil { 56 return nil, err 57 } 58 reqUrl.Path = strings.Replace(reqUrl.Path, "{refund_id}", url.PathEscape(*request.RefundId), -1) 59 reqBody, err := json.Marshal(request) 60 if err != nil { 61 return nil, err 62 } 63 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 64 if err != nil { 65 return nil, err 66 } 67 httpRequest.Header.Set("Accept", "application/json") 68 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 69 httpRequest.Header.Set("Content-Type", "application/json") 70 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 71 if err != nil { 72 return nil, err 73 } 74 httpRequest.Header.Set("Authorization", authorization) 75 76 client := &http.Client{} 77 httpResponse, err := client.Do(httpRequest) 78 if err != nil { 79 return nil, err 80 } 81 82 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 83 if err != nil { 84 return nil, err 85 } 86 87 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 88 // 2XX 成功,验证应答签名 89 err = wxpay_utility.ValidateResponse( 90 config.WechatPayPublicKeyId(), 91 config.WechatPayPublicKey(), 92 &httpResponse.Header, 93 respBody, 94 ) 95 if err != nil { 96 return nil, err 97 } 98 99 if err := json.Unmarshal(respBody, response); err != nil { 100 return nil, err 101 } 102 103 return response, nil 104 } else { 105 return nil, &wxpay_utility.ApiException{ 106 StatusCode: httpResponse.StatusCode, 107 Header: httpResponse.Header, 108 Body: respBody, 109 } 110 } 111} 112 113type Status string 114 115func (e Status) Ptr() *Status { 116 return &e 117} 118 119const ( 120 STATUS_SUCCESS Status = "SUCCESS" 121 STATUS_CLOSED Status = "CLOSED" 122 STATUS_PROCESSING Status = "PROCESSING" 123 STATUS_ABNORMAL Status = "ABNORMAL" 124) 125 126type Account string 127 128func (e Account) Ptr() *Account { 129 return &e 130} 131 132const ( 133 ACCOUNT_AVAILABLE Account = "AVAILABLE" 134 ACCOUNT_UNAVAILABLE Account = "UNAVAILABLE" 135) 136 137type PromotionType string 138 139func (e PromotionType) Ptr() *PromotionType { 140 return &e 141} 142 143const ( 144 PROMOTIONTYPE_COUPON PromotionType = "COUPON" 145 PROMOTIONTYPE_DISCOUNT PromotionType = "DISCOUNT" 146) 147 148type GoodsDetail struct { 149 MerchantGoodsId *string `json:"merchant_goods_id,omitempty"` 150 WechatpayGoodsId *string `json:"wechatpay_goods_id,omitempty"` 151 GoodsName *string `json:"goods_name,omitempty"` 152 UnitPrice *int64 `json:"unit_price,omitempty"` 153 RefundAmount *int64 `json:"refund_amount,omitempty"` 154 RefundQuantity *int64 `json:"refund_quantity,omitempty"` 155} 156 157type Channel string 158 159func (e Channel) Ptr() *Channel { 160 return &e 161} 162 163const ( 164 CHANNEL_ORIGINAL Channel = "ORIGINAL" 165 CHANNEL_BALANCE Channel = "BALANCE" 166 CHANNEL_OTHER_BALANCE Channel = "OTHER_BALANCE" 167 CHANNEL_OTHER_BANKCARD Channel = "OTHER_BANKCARD" 168) 169 170type Amount struct { 171 Total *int64 `json:"total,omitempty"` 172 Refund *int64 `json:"refund,omitempty"` 173 From []FundsFromItem `json:"from,omitempty"` 174 PayerTotal *int64 `json:"payer_total,omitempty"` 175 PayerRefund *int64 `json:"payer_refund,omitempty"` 176 SettlementRefund *int64 `json:"settlement_refund,omitempty"` 177 SettlementTotal *int64 `json:"settlement_total,omitempty"` 178 DiscountRefund *int64 `json:"discount_refund,omitempty"` 179 Currency *string `json:"currency,omitempty"` 180 RefundFee *int64 `json:"refund_fee,omitempty"` 181} 182 183type AbnormalReceiveType string 184 185func (e AbnormalReceiveType) Ptr() *AbnormalReceiveType { 186 return &e 187} 188 189const ( 190 ABNORMALRECEIVETYPE_USER_BANK_CARD AbnormalReceiveType = "USER_BANK_CARD" 191 ABNORMALRECEIVETYPE_MERCHANT_BANK_CARD AbnormalReceiveType = "MERCHANT_BANK_CARD" 192) 193 194type FundsAccount string 195 196func (e FundsAccount) Ptr() *FundsAccount { 197 return &e 198} 199 200const ( 201 FUNDSACCOUNT_UNSETTLED FundsAccount = "UNSETTLED" 202 FUNDSACCOUNT_AVAILABLE FundsAccount = "AVAILABLE" 203 FUNDSACCOUNT_UNAVAILABLE FundsAccount = "UNAVAILABLE" 204 FUNDSACCOUNT_OPERATION FundsAccount = "OPERATION" 205 FUNDSACCOUNT_BASIC FundsAccount = "BASIC" 206 FUNDSACCOUNT_ECNY_BASIC FundsAccount = "ECNY_BASIC" 207) 208 209type CreateAbnormalRefundRequest struct { 210 RefundId *string `json:"refund_id,omitempty"` 211 OutRefundNo *string `json:"out_refund_no,omitempty"` 212 Type *AbnormalReceiveType `json:"type,omitempty"` 213 BankType *string `json:"bank_type,omitempty"` 214 BankAccount *string `json:"bank_account,omitempty"` 215 RealName *string `json:"real_name,omitempty"` 216} 217 218func (o *CreateAbnormalRefundRequest) MarshalJSON() ([]byte, error) { 219 type Alias CreateAbnormalRefundRequest 220 a := &struct { 221 RefundId *string `json:"refund_id,omitempty"` 222 *Alias 223 }{ 224 // 序列化时移除非 Body 字段 225 RefundId: nil, 226 Alias: (*Alias)(o), 227 } 228 return json.Marshal(a) 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 Refund struct { 241 RefundId *string `json:"refund_id,omitempty"` 242 OutRefundNo *string `json:"out_refund_no,omitempty"` 243 TransactionId *string `json:"transaction_id,omitempty"` 244 OutTradeNo *string `json:"out_trade_no,omitempty"` 245 Channel *Channel `json:"channel,omitempty"` 246 UserReceivedAccount *string `json:"user_received_account,omitempty"` 247 SuccessTime *string `json:"success_time,omitempty"` 248 CreateTime *string `json:"create_time,omitempty"` 249 Status *Status `json:"status,omitempty"` 250 FundsAccount *FundsAccount `json:"funds_account,omitempty"` 251 Amount *Amount `json:"amount,omitempty"` 252 PromotionDetail []Promotion `json:"promotion_detail,omitempty"` 253} 254 255type FundsFromItem struct { 256 Account *Account `json:"account,omitempty"` 257 Amount *int64 `json:"amount,omitempty"` 258} 259 260type PromotionScope string 261 262func (e PromotionScope) Ptr() *PromotionScope { 263 return &e 264} 265 266const ( 267 PROMOTIONSCOPE_GLOBAL PromotionScope = "GLOBAL" 268 PROMOTIONSCOPE_SINGLE PromotionScope = "SINGLE" 269)
POST
1curl -X POST \ 2 https://api.mch.weixin.qq.com/v3/refund/domestic/refunds/50000000382019052709732678859/apply-abnormal-refund \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" \ 5 -H "Wechatpay-Serial: 5157F09EFDC096DE15EBE81A47057A7232F1B8E1" \ 6 -H "Content-Type: application/json" \ 7 -d '{ 8 "out_refund_no" : "1217752501201407033233368018", 9 "type" : "USER_BANK_CARD", 10 "bank_type" : "ICBC_DEBIT", 11 "bank_account" : "d+xT+MQCvrLHUVDWv/8MR/dB7TkXLVfSrUxMPZy6jWWYzpRrEEaYQE8ZRGYoeorwC+w==", 12 "real_name" : "UPgQcZSdq3zOayJwZ5XLrHY2dZU1W2Cd" 13 }' 14
应答参数
|
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(32) 【优惠范围】优惠活动中代金券的适用范围,分为两种类型: type 必填 string(32) 【优惠类型】代金券资金类型,优惠活动中代金券的结算资金类型,分为两种类型: 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 | 系统异常,请稍后重试 | 请稍后重试 |
业务错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | INVALID_REQUEST | 请求参数符合参数格式,但不符合业务规则 | 此状态代表本次请求的退款申请失败,请根据具体的错误提示做相应处理。 |
401 | SIGN_ERROR | 签名错误 | 请检查签名参数和方法是否都符合签名算法要求,参考:如何生成签名 |
404 | RESOURCE_NOT_EXISTS | 退款单不存在 | 请检查退款单号是否有误 |
429 | FREQUENCY_LIMITED | 频率限制 | 该笔退款未受理,请降低频率后重试 |
500 | SYSTEM_ERROR | 系统超时等 | 请不要更换商户退款单号,请使用相同参数再次调用API。 |