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