解冻剩余资金
更新时间:2025.09.29不需要进行分账的订单,可直接调用本接口将订单的金额全部解冻给本商户
调用分账接口后,需要解冻剩余资金时,调用本接口将剩余的分账金额全部解冻给本商户
此接口采用异步处理模式,即在接收到商户请求后,优先受理请求再异步处理,最终的分账结果可以通过查询分账接口获取
接口说明
支持商户:【普通服务商】
请求方式:【POST】/v3/profitsharing/orders/unfreeze
请求域名:【主域名】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
body 包体参数
sub_mchid 必填 string(32)
【特约商户号】 微信支付分配的特约商户号,即分账的出资商户号
transaction_id 必填 string(32)
【微信订单号】 微信支付订单号
out_order_no 必填 string(64)
【商户分账单号】 商户系统内部的分账单号,在商户系统内部唯一,同一分账单号多次请求等同一次。只能是数字、大小写字母_-|*@
description 必填 string(80)
【解冻剩余资金描述】 描述解冻剩余资金的原因
请求示例
POST
1curl -X POST \ 2 https://api.mch.weixin.qq.com/v3/profitsharing/orders/unfreeze \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" \ 5 -H "Content-Type: application/json" \ 6 -d '{ 7 "sub_mchid" : "1900000109", 8 "transaction_id" : "4208450740201411110007820472", 9 "out_order_no" : "P20150806125346", 10 "description" : "解冻全部剩余资金" 11 }' 12
需配合微信支付工具库 WXPayUtility 使用,请参考Java
1package com.java.demo; 2 3import com.java.utils.WXPayUtility; // 引用微信支付工具库,参考:https://pay.weixin.qq.com/doc/v3/partner/4014985777 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 UnfreezeOrder { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "POST"; 28 private static String PATH = "/v3/profitsharing/orders/unfreeze"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 UnfreezeOrder client = new UnfreezeOrder( 33 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 34 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 35 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 36 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 37 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径,本地文件路径 38 ); 39 40 UnfreezeOrderRequest request = new UnfreezeOrderRequest(); 41 request.subMchid = "1900000109"; 42 request.transactionId = "4208450740201411110007820472"; 43 request.outOrderNo = "P20150806125346"; 44 request.description = "解冻全部剩余资金"; 45 try { 46 OrdersEntity response = client.run(request); 47 // TODO: 请求成功,继续业务逻辑 48 System.out.println(response); 49 } catch (WXPayUtility.ApiException e) { 50 // TODO: 请求失败,根据状态码执行不同的逻辑 51 e.printStackTrace(); 52 } 53 } 54 55 public OrdersEntity run(UnfreezeOrderRequest request) { 56 String uri = PATH; 57 String reqBody = WXPayUtility.toJson(request); 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, reqBody)); 63 reqBuilder.addHeader("Content-Type", "application/json"); 64 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 65 reqBuilder.method(METHOD, requestBody); 66 Request httpRequest = reqBuilder.build(); 67 68 // 发送HTTP请求 69 OkHttpClient client = new OkHttpClient.Builder().build(); 70 try (Response httpResponse = client.newCall(httpRequest).execute()) { 71 String respBody = WXPayUtility.extractBody(httpResponse); 72 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 73 // 2XX 成功,验证应答签名 74 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 75 httpResponse.headers(), respBody); 76 77 // 从HTTP应答报文构建返回数据 78 return WXPayUtility.fromJson(respBody, OrdersEntity.class); 79 } else { 80 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 81 } 82 } catch (IOException e) { 83 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 84 } 85 } 86 87 private final String mchid; 88 private final String certificateSerialNo; 89 private final PrivateKey privateKey; 90 private final String wechatPayPublicKeyId; 91 private final PublicKey wechatPayPublicKey; 92 93 public UnfreezeOrder(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 94 this.mchid = mchid; 95 this.certificateSerialNo = certificateSerialNo; 96 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 97 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 98 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 99 } 100 101 public static class UnfreezeOrderRequest { 102 @SerializedName("sub_mchid") 103 public String subMchid; 104 105 @SerializedName("transaction_id") 106 public String transactionId; 107 108 @SerializedName("out_order_no") 109 public String outOrderNo; 110 111 @SerializedName("description") 112 public String description; 113 } 114 115 public static class OrdersEntity { 116 @SerializedName("sub_mchid") 117 public String subMchid; 118 119 @SerializedName("transaction_id") 120 public String transactionId; 121 122 @SerializedName("out_order_no") 123 public String outOrderNo; 124 125 @SerializedName("order_id") 126 public String orderId; 127 128 @SerializedName("state") 129 public OrderStatus state; 130 131 @SerializedName("receivers") 132 public List<OrderReceiverDetail> receivers = new ArrayList<OrderReceiverDetail>(); 133 } 134 135 public enum OrderStatus { 136 @SerializedName("PROCESSING") 137 PROCESSING, 138 @SerializedName("FINISHED") 139 FINISHED 140 } 141 142 public static class OrderReceiverDetail { 143 @SerializedName("amount") 144 public Long amount; 145 146 @SerializedName("description") 147 public String description; 148 149 @SerializedName("type") 150 public ReceiverType type; 151 152 @SerializedName("account") 153 public String account; 154 155 @SerializedName("result") 156 public DetailStatus result; 157 158 @SerializedName("fail_reason") 159 public DetailFailReason failReason; 160 161 @SerializedName("create_time") 162 public String createTime; 163 164 @SerializedName("finish_time") 165 public String finishTime; 166 167 @SerializedName("detail_id") 168 public String detailId; 169 } 170 171 public enum ReceiverType { 172 @SerializedName("MERCHANT_ID") 173 MERCHANT_ID, 174 @SerializedName("PERSONAL_OPENID") 175 PERSONAL_OPENID, 176 @SerializedName("PERSONAL_SUB_OPENID") 177 PERSONAL_SUB_OPENID 178 } 179 180 public enum DetailStatus { 181 @SerializedName("PENDING") 182 PENDING, 183 @SerializedName("SUCCESS") 184 SUCCESS, 185 @SerializedName("CLOSED") 186 CLOSED 187 } 188 189 public enum DetailFailReason { 190 @SerializedName("ACCOUNT_ABNORMAL") 191 ACCOUNT_ABNORMAL, 192 @SerializedName("NO_RELATION") 193 NO_RELATION, 194 @SerializedName("RECEIVER_HIGH_RISK") 195 RECEIVER_HIGH_RISK, 196 @SerializedName("RECEIVER_REAL_NAME_NOT_VERIFIED") 197 RECEIVER_REAL_NAME_NOT_VERIFIED, 198 @SerializedName("NO_AUTH") 199 NO_AUTH, 200 @SerializedName("RECEIVER_RECEIPT_LIMIT") 201 RECEIVER_RECEIPT_LIMIT, 202 @SerializedName("PAYER_ACCOUNT_ABNORMAL") 203 PAYER_ACCOUNT_ABNORMAL, 204 @SerializedName("INVALID_REQUEST") 205 INVALID_REQUEST 206 } 207 208} 209
需配合微信支付工具库 wxpay_utility 使用,请参考Go
1package main 2 3import ( 4 "bytes" 5 "demo/wxpay_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/v3/partner/4015119446 6 "encoding/json" 7 "fmt" 8 "net/http" 9 "net/url" 10 "time" 11) 12 13func main() { 14 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 15 config, err := wxpay_utility.CreateMchConfig( 16 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 17 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 18 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 19 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 20 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 21 ) 22 if err != nil { 23 fmt.Println(err) 24 return 25 } 26 27 request := &UnfreezeOrderRequest{ 28 SubMchid: wxpay_utility.String("1900000109"), 29 TransactionId: wxpay_utility.String("4208450740201411110007820472"), 30 OutOrderNo: wxpay_utility.String("P20150806125346"), 31 Description: wxpay_utility.String("解冻全部剩余资金"), 32 } 33 34 response, err := UnfreezeOrder(config, request) 35 if err != nil { 36 fmt.Printf("请求失败: %+v\n", err) 37 // TODO: 请求失败,根据状态码执行不同的处理 38 return 39 } 40 41 // TODO: 请求成功,继续业务逻辑 42 fmt.Printf("请求成功: %+v\n", response) 43} 44 45func UnfreezeOrder(config *wxpay_utility.MchConfig, request *UnfreezeOrderRequest) (response *OrdersEntity, err error) { 46 const ( 47 host = "https://api.mch.weixin.qq.com" 48 method = "POST" 49 path = "/v3/profitsharing/orders/unfreeze" 50 ) 51 52 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 53 if err != nil { 54 return nil, err 55 } 56 reqBody, err := json.Marshal(request) 57 if err != nil { 58 return nil, err 59 } 60 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 61 if err != nil { 62 return nil, err 63 } 64 httpRequest.Header.Set("Accept", "application/json") 65 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 66 httpRequest.Header.Set("Content-Type", "application/json") 67 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 68 if err != nil { 69 return nil, err 70 } 71 httpRequest.Header.Set("Authorization", authorization) 72 73 client := &http.Client{} 74 httpResponse, err := client.Do(httpRequest) 75 if err != nil { 76 return nil, err 77 } 78 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 79 if err != nil { 80 return nil, err 81 } 82 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 83 // 2XX 成功,验证应答签名 84 err = wxpay_utility.ValidateResponse( 85 config.WechatPayPublicKeyId(), 86 config.WechatPayPublicKey(), 87 &httpResponse.Header, 88 respBody, 89 ) 90 if err != nil { 91 return nil, err 92 } 93 response := &OrdersEntity{} 94 if err := json.Unmarshal(respBody, response); err != nil { 95 return nil, err 96 } 97 98 return response, nil 99 } else { 100 return nil, wxpay_utility.NewApiException( 101 httpResponse.StatusCode, 102 httpResponse.Header, 103 respBody, 104 ) 105 } 106} 107 108type UnfreezeOrderRequest struct { 109 SubMchid *string `json:"sub_mchid,omitempty"` 110 TransactionId *string `json:"transaction_id,omitempty"` 111 OutOrderNo *string `json:"out_order_no,omitempty"` 112 Description *string `json:"description,omitempty"` 113} 114 115type OrdersEntity struct { 116 SubMchid *string `json:"sub_mchid,omitempty"` 117 TransactionId *string `json:"transaction_id,omitempty"` 118 OutOrderNo *string `json:"out_order_no,omitempty"` 119 OrderId *string `json:"order_id,omitempty"` 120 State *OrderStatus `json:"state,omitempty"` 121 Receivers []OrderReceiverDetail `json:"receivers,omitempty"` 122} 123 124type OrderStatus string 125 126func (e OrderStatus) Ptr() *OrderStatus { 127 return &e 128} 129 130const ( 131 ORDERSTATUS_PROCESSING OrderStatus = "PROCESSING" 132 ORDERSTATUS_FINISHED OrderStatus = "FINISHED" 133) 134 135type OrderReceiverDetail struct { 136 Amount *int64 `json:"amount,omitempty"` 137 Description *string `json:"description,omitempty"` 138 Type *ReceiverType `json:"type,omitempty"` 139 Account *string `json:"account,omitempty"` 140 Result *DetailStatus `json:"result,omitempty"` 141 FailReason *DetailFailReason `json:"fail_reason,omitempty"` 142 CreateTime *time.Time `json:"create_time,omitempty"` 143 FinishTime *time.Time `json:"finish_time,omitempty"` 144 DetailId *string `json:"detail_id,omitempty"` 145} 146 147type ReceiverType string 148 149func (e ReceiverType) Ptr() *ReceiverType { 150 return &e 151} 152 153const ( 154 RECEIVERTYPE_MERCHANT_ID ReceiverType = "MERCHANT_ID" 155 RECEIVERTYPE_PERSONAL_OPENID ReceiverType = "PERSONAL_OPENID" 156 RECEIVERTYPE_PERSONAL_SUB_OPENID ReceiverType = "PERSONAL_SUB_OPENID" 157) 158 159type DetailStatus string 160 161func (e DetailStatus) Ptr() *DetailStatus { 162 return &e 163} 164 165const ( 166 DETAILSTATUS_PENDING DetailStatus = "PENDING" 167 DETAILSTATUS_SUCCESS DetailStatus = "SUCCESS" 168 DETAILSTATUS_CLOSED DetailStatus = "CLOSED" 169) 170 171type DetailFailReason string 172 173func (e DetailFailReason) Ptr() *DetailFailReason { 174 return &e 175} 176 177const ( 178 DETAILFAILREASON_ACCOUNT_ABNORMAL DetailFailReason = "ACCOUNT_ABNORMAL" 179 DETAILFAILREASON_NO_RELATION DetailFailReason = "NO_RELATION" 180 DETAILFAILREASON_RECEIVER_HIGH_RISK DetailFailReason = "RECEIVER_HIGH_RISK" 181 DETAILFAILREASON_RECEIVER_REAL_NAME_NOT_VERIFIED DetailFailReason = "RECEIVER_REAL_NAME_NOT_VERIFIED" 182 DETAILFAILREASON_NO_AUTH DetailFailReason = "NO_AUTH" 183 DETAILFAILREASON_RECEIVER_RECEIPT_LIMIT DetailFailReason = "RECEIVER_RECEIPT_LIMIT" 184 DETAILFAILREASON_PAYER_ACCOUNT_ABNORMAL DetailFailReason = "PAYER_ACCOUNT_ABNORMAL" 185 DETAILFAILREASON_INVALID_REQUEST DetailFailReason = "INVALID_REQUEST" 186) 187
应答参数
200 OK
sub_mchid 必填 string(32)
【特约商户号】 微信支付分配的特约商户号,即分账的出资商户号
transaction_id 必填 string(32)
【微信订单号】 微信支付订单号
out_order_no 必填 string(64)
【商户分账单号】 请求分账时的商户分账单号
order_id 必填 string(64)
【微信分账单号】 微信分账单号,微信系统返回的唯一标识
state 必填 string
【分账单状态】 分账单状态(每个接收方的分账结果请查看receivers中的result字段)
可选取值
PROCESSING
: 处理中,非终态,分账结果存在非终态,可稍后再次查询,直到状态为FINISHED。FINISHED
: 分账完成,终态,仅代表分账动账执行完毕,每个接收方的分账结果请查看receivers中的result字段
receivers 必填 array[object]
【分账接收方列表】 分账接收方列表
属性 | |
amount 必填 integer 【分账金额】 分账金额,单位为分,只能为整数,不能超过原订单支付金额及最大分账比例金额 description 必填 string(80) 【解冻剩余资金描述】 描述解冻剩余资金的原因 type 必填 string 【接收方类型】 接收方类型 可选取值
account 必填 string(64) 【接收方账号】
result 必填 string 【分账结果】 分账结果 可选取值
fail_reason 选填 string 【分账失败原因】 分账失败原因,当分账结果result为CLOSED(已关闭)时,返回该字段,具体处理方案请参考分账失败处理指引。 可选取值
create_time 必填 string 【分账创建时间】 分账创建时间,需遵循 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秒。 finish_time 必填 string 【分账完成时间】 分账完成时间,需遵循 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秒。 detail_id 必填 string(64) 【分账明细单号】 微信分账明细单号,每笔分账业务执行的明细单号,可与资金账单对账使用,对应资金账单中的“业务凭证号” |
应答示例
200 OK
1{ 2 "sub_mchid" : "1900000109", 3 "transaction_id" : "4208450740201411110007820472", 4 "out_order_no" : "P20150806125346", 5 "order_id" : "3008450740201411110007820472", 6 "state" : "FINISHED", 7 "receivers" : [ 8 { 9 "amount" : 100, 10 "description" : "分给商户1900000110", 11 "type" : "MERCHANT_ID", 12 "account" : "1900000109", 13 "result" : "SUCCESS", 14 "fail_reason" : "ACCOUNT_ABNORMAL", 15 "create_time" : "2015-05-20T13:29:35.120+08:00", 16 "finish_time" : "2015-05-20T13:29:35.120+08:00", 17 "detail_id" : "36011111111111111111111" 18 } 19 ] 20} 21
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示