请求分账
更新时间:2025.09.29微信订单支付成功后,由电商平台发起分账请求,将结算后的资金分给分账接收方。
注意:
微信订单支付成功后,平台商户代平台二级商户发起分账请求,将结算后的钱分到分账接收方。
对同一笔订单最多能发起50次分账请求,每次请求最多分给50个接收方。
此接口采用异步处理模式,即在接收到商户请求后,会先受理请求再异步处理,最终的分账结果可以通过查询分账接口获取。
分账资金的冻结期默认是180天。从订单支付成功之日起,180天内需要发起分账,若180天内未发起分账,待分账资金将会自动解冻给分账方。
电商平台需确保向微信支付传输用户身份信息和账号标识信息做一致性校验已合法征得用户授权
接口支持幂等重入
接口限频:
单个平台商户(请求分账) 2000QPS,如果超过频率限制,会报错FREQUENCY_LIMITED,请降低频率请求。
单个交易收款商户(请求分账) 300QPS,如果超过频率限制,会报错FREQUENCY_LIMITED,请降低频率请求。同时,建议对同一主体的商户拆分多个商户号进行交易,避免交易集中到单个商户。
接口说明
支持商户:【平台商户】
请求方式:【POST】/v3/ecommerce/profitsharing/orders
请求域名:【主域名】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
Wechatpay-Serial 必填 string
【微信支付公钥ID】或【微信支付平台证书序列号】 请求参数中的敏感字段,需要使用微信支付公钥加密(推荐),请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引;也可以使用微信支付平台证书公钥加密,参考获取平台证书序列号、平台证书加密敏感信息指引
body 包体参数
appid 选填 string(32)
【公众账号ID】 APPID是微信开放平台(移动应用)或微信公众平台(小程序、公众号)为开发者的应用程序提供的唯一标识。此处,可以填写这三种类型中的任意一种APPID,但请确保该appid与mchid有绑定关系。详见:开发必要参数说明。分账接收方类型包含PERSONAL_OPENID时必填
sub_mchid 必填 string(32)
【电商平台二级商户号】 微信支付分配的电商平台二级商户号,即分账的出资商户号。
transaction_id 必填 string(32)
【微信订单号】 微信支付订单号
out_order_no 必填 string(64)
【商户分账单号】 商户系统内部的分账单号,在商户系统内部唯一(单次分账、多次分账、完结分账应使用不同的商户分账单号),同一分账单号多次请求等同一次。只能是数字、大小写字母_-|*@
receivers 必填 array[object]
【分账接收方列表】 分账接收方列表,可以设置出资商户作为分账接受方
属性 | |
type 必填 string(32) 【分账接收方类型】 可选取值:
receiver_account 必填 string(64) 【分账接收方账号】
amount 必填 integer 【分账金额】 分账金额,单位为分,只能为整数,不能超过原订单支付金额及最大分账比例金额。调整最大分账比例:登录合作伙伴商户平台,进入以下页面:产品中心-我的工具箱-电商收付通-供应链分账设置 description 必填 string(80) 【分账描述】 分账的原因描述,会在查询分账结果接口和分账账单中原样返回 receiver_name 选填 string(10240) 【分账个人接收方姓名】
|
finish 必填 boolean
【是否分账完成】
如果为true,则分账接收商户只支持平台商户,且该笔订单剩余未分账的金额会解冻回电商平台二级商户,解冻后不支持对该笔订单再次进行分账;
如果为false,则分账接收商户可以为平台商户或者平台二级商户,且该笔订单剩余未分账的金额不会解冻回平台二级商户,可以对该笔订单再次进行分账;
请求示例
POST
1curl -X POST \ 2 https://api.mch.weixin.qq.com/v3/ecommerce/profitsharing/orders \ 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 "appid" : "wx8888888888888888", 9 "sub_mchid" : "1900000109", 10 "transaction_id" : "4208450740201411110007820472", 11 "out_order_no" : "P20150806125346", 12 "receivers" : [ 13 { 14 "type" : "MERCHANT_ID", 15 "receiver_account" : "1900000109", 16 "amount" : 100, 17 "description" : "分给商户1900000110", 18 "receiver_name" : "hu89ohu89ohu89o" 19 } 20 ], 21 "finish" : true 22 }' 23
需配合微信支付工具库 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 CreateOrder { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "POST"; 28 private static String PATH = "/v3/ecommerce/profitsharing/orders"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 CreateOrder client = new CreateOrder( 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 CreateOrderRequest request = new CreateOrderRequest(); 41 request.appid = "wx8888888888888888"; 42 request.subMchid = "1900000109"; 43 request.transactionId = "4208450740201411110007820472"; 44 request.outOrderNo = "P20150806125346"; 45 request.receivers = new ArrayList<>(); 46 { 47 CreateOrderReceiver receiversItem = new CreateOrderReceiver(); 48 receiversItem.type = "MERCHANT_ID"; 49 receiversItem.receiverAccount = "1900000109"; 50 receiversItem.amount = 100L; 51 receiversItem.description = "分给商户1900000110"; 52 receiversItem.receiverName = client.encrypt("receiver_name"); 53 request.receivers.add(receiversItem); 54 }; 55 request.finish = true; 56 try { 57 CreateOrderResponse response = client.run(request); 58 // TODO: 请求成功,继续业务逻辑 59 System.out.println(response); 60 } catch (WXPayUtility.ApiException e) { 61 // TODO: 请求失败,根据状态码执行不同的逻辑 62 e.printStackTrace(); 63 } 64 } 65 66 public CreateOrderResponse run(CreateOrderRequest request) { 67 String uri = PATH; 68 String reqBody = WXPayUtility.toJson(request); 69 70 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 71 reqBuilder.addHeader("Accept", "application/json"); 72 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 73 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo,privateKey, METHOD, uri, reqBody)); 74 reqBuilder.addHeader("Content-Type", "application/json"); 75 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 76 reqBuilder.method(METHOD, requestBody); 77 Request httpRequest = reqBuilder.build(); 78 79 // 发送HTTP请求 80 OkHttpClient client = new OkHttpClient.Builder().build(); 81 try (Response httpResponse = client.newCall(httpRequest).execute()) { 82 String respBody = WXPayUtility.extractBody(httpResponse); 83 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 84 // 2XX 成功,验证应答签名 85 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 86 httpResponse.headers(), respBody); 87 88 // 从HTTP应答报文构建返回数据 89 return WXPayUtility.fromJson(respBody, CreateOrderResponse.class); 90 } else { 91 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 92 } 93 } catch (IOException e) { 94 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 95 } 96 } 97 98 private final String mchid; 99 private final String certificateSerialNo; 100 private final PrivateKey privateKey; 101 private final String wechatPayPublicKeyId; 102 private final PublicKey wechatPayPublicKey; 103 104 public CreateOrder(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 105 this.mchid = mchid; 106 this.certificateSerialNo = certificateSerialNo; 107 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 108 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 109 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 110 } 111 112 public String encrypt(String plainText) { 113 return WXPayUtility.encrypt(this.wechatPayPublicKey, plainText); 114 } 115 116 public static class CreateOrderRequest { 117 @SerializedName("appid") 118 public String appid; 119 120 @SerializedName("sub_mchid") 121 public String subMchid; 122 123 @SerializedName("transaction_id") 124 public String transactionId; 125 126 @SerializedName("out_order_no") 127 public String outOrderNo; 128 129 @SerializedName("receivers") 130 public List<CreateOrderReceiver> receivers = new ArrayList<CreateOrderReceiver>(); 131 132 @SerializedName("finish") 133 public Boolean finish; 134 } 135 136 public static class CreateOrderResponse { 137 @SerializedName("sub_mchid") 138 public String subMchid; 139 140 @SerializedName("transaction_id") 141 public String transactionId; 142 143 @SerializedName("out_order_no") 144 public String outOrderNo; 145 146 @SerializedName("order_id") 147 public String orderId; 148 149 @SerializedName("receivers") 150 public List<OrderReceiverDetail> receivers = new ArrayList<OrderReceiverDetail>(); 151 152 @SerializedName("status") 153 public Status status; 154 } 155 156 public static class CreateOrderReceiver { 157 @SerializedName("type") 158 public String type; 159 160 @SerializedName("receiver_account") 161 public String receiverAccount; 162 163 @SerializedName("amount") 164 public Long amount; 165 166 @SerializedName("description") 167 public String description; 168 169 @SerializedName("receiver_name") 170 public String receiverName; 171 } 172 173 public static class OrderReceiverDetail { 174 @SerializedName("amount") 175 public Long amount; 176 177 @SerializedName("description") 178 public String description; 179 180 @SerializedName("result") 181 public String result; 182 183 @SerializedName("finish_time") 184 public String finishTime; 185 186 @SerializedName("fail_reason") 187 public String failReason; 188 189 @SerializedName("type") 190 public String type; 191 192 @SerializedName("receiver_account") 193 public String receiverAccount; 194 195 @SerializedName("detail_id") 196 public String detailId; 197 } 198 199 public enum Status { 200 @SerializedName("PROCESSING") 201 PROCESSING, 202 @SerializedName("FINISHED") 203 FINISHED 204 } 205 206} 207
需配合微信支付工具库 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 := &CreateOrderRequest{ 28 Appid: wxpay_utility.String("wx8888888888888888"), 29 SubMchid: wxpay_utility.String("1900000109"), 30 TransactionId: wxpay_utility.String("4208450740201411110007820472"), 31 OutOrderNo: wxpay_utility.String("P20150806125346"), 32 Receivers: []CreateOrderReceiver{CreateOrderReceiver{ 33 Type: wxpay_utility.String("MERCHANT_ID"), 34 ReceiverAccount: wxpay_utility.String("1900000109"), 35 Amount: wxpay_utility.Int64(100), 36 Description: wxpay_utility.String("分给商户1900000110"), 37 ReceiverName: wxpay_utility.String("hu89ohu89ohu89o"), /*请传入wxpay_utility.EncryptOAEPWithPublicKey 加密结果*/ 38 }}, 39 Finish: wxpay_utility.Bool(true), 40 } 41 42 response, err := CreateOrder(config, request) 43 if err != nil { 44 fmt.Printf("请求失败: %+v\n", err) 45 // TODO: 请求失败,根据状态码执行不同的处理 46 return 47 } 48 49 // TODO: 请求成功,继续业务逻辑 50 fmt.Printf("请求成功: %+v\n", response) 51} 52 53func CreateOrder(config *wxpay_utility.MchConfig, request *CreateOrderRequest) (response *CreateOrderResponse, err error) { 54 const ( 55 host = "https://api.mch.weixin.qq.com" 56 method = "POST" 57 path = "/v3/ecommerce/profitsharing/orders" 58 ) 59 60 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 61 if err != nil { 62 return nil, err 63 } 64 reqBody, err := json.Marshal(request) 65 if err != nil { 66 return nil, err 67 } 68 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 69 if err != nil { 70 return nil, err 71 } 72 httpRequest.Header.Set("Accept", "application/json") 73 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 74 httpRequest.Header.Set("Content-Type", "application/json") 75 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 76 if err != nil { 77 return nil, err 78 } 79 httpRequest.Header.Set("Authorization", authorization) 80 81 client := &http.Client{} 82 httpResponse, err := client.Do(httpRequest) 83 if err != nil { 84 return nil, err 85 } 86 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 87 if err != nil { 88 return nil, err 89 } 90 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 91 // 2XX 成功,验证应答签名 92 err = wxpay_utility.ValidateResponse( 93 config.WechatPayPublicKeyId(), 94 config.WechatPayPublicKey(), 95 &httpResponse.Header, 96 respBody, 97 ) 98 if err != nil { 99 return nil, err 100 } 101 response := &CreateOrderResponse{} 102 if err := json.Unmarshal(respBody, response); err != nil { 103 return nil, err 104 } 105 106 return response, nil 107 } else { 108 return nil, wxpay_utility.NewApiException( 109 httpResponse.StatusCode, 110 httpResponse.Header, 111 respBody, 112 ) 113 } 114} 115 116type CreateOrderRequest struct { 117 Appid *string `json:"appid,omitempty"` 118 SubMchid *string `json:"sub_mchid,omitempty"` 119 TransactionId *string `json:"transaction_id,omitempty"` 120 OutOrderNo *string `json:"out_order_no,omitempty"` 121 Receivers []CreateOrderReceiver `json:"receivers,omitempty"` 122 Finish *bool `json:"finish,omitempty"` 123} 124 125type CreateOrderResponse struct { 126 SubMchid *string `json:"sub_mchid,omitempty"` 127 TransactionId *string `json:"transaction_id,omitempty"` 128 OutOrderNo *string `json:"out_order_no,omitempty"` 129 OrderId *string `json:"order_id,omitempty"` 130 Receivers []OrderReceiverDetail `json:"receivers,omitempty"` 131 Status *Status `json:"status,omitempty"` 132} 133 134type CreateOrderReceiver struct { 135 Type *string `json:"type,omitempty"` 136 ReceiverAccount *string `json:"receiver_account,omitempty"` 137 Amount *int64 `json:"amount,omitempty"` 138 Description *string `json:"description,omitempty"` 139 ReceiverName *string `json:"receiver_name,omitempty"` 140} 141 142type OrderReceiverDetail struct { 143 Amount *int64 `json:"amount,omitempty"` 144 Description *string `json:"description,omitempty"` 145 Result *string `json:"result,omitempty"` 146 FinishTime *time.Time `json:"finish_time,omitempty"` 147 FailReason *string `json:"fail_reason,omitempty"` 148 Type *string `json:"type,omitempty"` 149 ReceiverAccount *string `json:"receiver_account,omitempty"` 150 DetailId *string `json:"detail_id,omitempty"` 151} 152 153type Status string 154 155func (e Status) Ptr() *Status { 156 return &e 157} 158 159const ( 160 STATUS_PROCESSING Status = "PROCESSING" 161 STATUS_FINISHED Status = "FINISHED" 162) 163
应答参数
200 OK
sub_mchid 必填 string(32)
【电商平台二级商户号】 微信支付分配的电商平台二级商户号,即分账的出资商户号。
transaction_id 必填 string(32)
【微信订单号】 微信支付订单号
out_order_no 必填 string(64)
【商户分账单号】 商户系统内部的分账单号,在商户系统内部唯一(单次分账、多次分账、完结分账应使用不同的商户分账单号),同一分账单号多次请求等同一次。只能是数字、大小写字母_-|*@
order_id 必填 string(64)
【微信分账单号】 微信分账单号,微信系统返回的唯一标识
receivers 必填 array[object]
【分账接收方列表】 分账接收方列表
属性 | |
amount 必填 integer 【分账金额】 分账金额,单位为分,只能为整数,不能超过原订单支付金额及最大分账比例金额 description 必填 string(80) 【分账描述】 分账的原因描述,会在查询分账结果接口和分账账单中原样返回 result 必填 string(32) 【分账结果】 可选取值:
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秒。 fail_reason 选填 string(64) 【分账失败原因】 分账失败原因,当分账结果result为CLOSED(已关闭)时,返回该字段,具体处理方案请参考分账失败处理指引。
type 必填 string(32) 【接收方类型】 可选取值:
receiver_account 必填 string(64) 【接收方账号】
detail_id 必填 string(64) 【分账明细单号】 微信分账明细单号,每笔分账业务执行的明细单号,可与资金账单对账使用,对应资金账单中的“业务凭证号” |
status 选填 string
【分账单状态】 分账单状态(每个接收方的分账结果请查看receivers中的result字段)
可选取值
PROCESSING
: 处理中,非终态,分账结果存在非终态,可稍后再次查询,直到状态为FINISHED。FINISHED
: 处理完成,终态,仅代表分账动账执行完毕,每个接收方的分账结果请查看receivers中的result字段
应答示例
200 OK
1{ 2 "sub_mchid" : "1900000109", 3 "transaction_id" : "4208450740201411110007820472", 4 "out_order_no" : "P20150806125346", 5 "order_id" : "3008450740201411110007820472", 6 "receivers" : [ 7 { 8 "amount" : 100, 9 "description" : "分给商户1900000110", 10 "result" : "SUCCESS", 11 "finish_time" : "2015-05-20T13:29:35.120+08:00", 12 "fail_reason" : "ACCOUNT_ABNORMAL", 13 "type" : "MERCHANT_ID", 14 "receiver_account" : "1900000109", 15 "detail_id" : "36011111111111111111111" 16 } 17 ], 18 "status" : "PROCESSING" 19} 20
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示