申请单个子商户资金账单
更新时间:2024.10.21下载接口说明
微信支付按天提供微信支付账户的资金流水账单文件,服务商可以通过该接口获取子商户账单文件的下载地址。文件内包含子商户资金操作相关的业务单号、收支金额、记账时间等信息,供商户进行核对。
|
文件格式说明
账单文件包括明细数据和汇总数据两部分,每一部分都包含一行表头和若干行具体数据。
明细数据每一行对应一笔资金操作,同时每一个数据前加入了字符`,以避免数据被Excel按科学计数法处理。如需汇总金额等数据,可以批量替换掉该字符。
接口说明
支持商户:【普通服务商】 【平台商户】
请求方式:【GET】/v3/bill/sub-merchant-fundflowbill
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
query 查询参数
sub_mchid 必填 string(12)
【子商户号】 子商户号,下载指定子商户的账单。
bill_date 必填 string(10)
【账单日期】 账单日期,格式yyyy-MM-DD,仅支持三个月内的账单下载申请。
account_type 必填 string
【资金账户类型】 资金账户类型
可选取值
BASIC
: 基本账户OPERATION
: 运营账户FEES
: 手续费账户DEPOSIT
: 保证金账户
algorithm 必填 string
【账单文件加密算法】 账单文件加密算法
可选取值
AEAD_AES_256_GCM
: AEAD_AES_256_GCM加密算法SM4_GCM
: SM4_GCM加密算法,密钥长度128bit
tar_type 选填 string
【压缩格式】 压缩格式,不填则以不压缩的方式返回数据流
可选取值
GZIP
: GZIP格式压缩,返回格式为.gzip的压缩包账单
请求示例
GET
1curl -X GET \ 2 https://api.mch.weixin.qq.com/v3/bill/sub-merchant-fundflowbill?sub_mchid=19000000001&bill_date=2019-06-11&account_type=BASIC&algorithm=AEAD_AES_256_GCM&tar_type=GZIP \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" 5
需配合微信支付工具库 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 * 申请单个子商户资金账单API 24 */ 25public class GetSingleSubMchFundFlowBill { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "GET"; 28 private static String PATH = "/v3/bill/sub-merchant-fundflowbill"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 GetSingleSubMchFundFlowBill client = new GetSingleSubMchFundFlowBill( 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 GetSingleSubMchFundFlowBillRequest request = new GetSingleSubMchFundFlowBillRequest(); 41 request.subMchid = "19000000001"; 42 request.billDate = "2019-06-11"; 43 request.accountType = SubMchFundFlowBillAccountType.BASIC; 44 request.algorithm = Algorithm.AEAD_AES_256_GCM; 45 request.tarType = TarType.GZIP; 46 try { 47 QueryEncryptBillEntity response = client.run(request); 48 // TODO: 请求成功,继续业务逻辑 49 System.out.println(response); 50 } catch (WXPayUtility.ApiException e) { 51 // TODO: 请求失败,根据状态码执行不同的逻辑 52 e.printStackTrace(); 53 } 54 } 55 56 public QueryEncryptBillEntity run(GetSingleSubMchFundFlowBillRequest request) { 57 String uri = PATH; 58 Map<String, Object> args = new HashMap<>(); 59 args.put("sub_mchid", request.subMchid); 60 args.put("bill_date", request.billDate); 61 args.put("account_type", request.accountType); 62 args.put("algorithm", request.algorithm); 63 args.put("tar_type", request.tarType); 64 String queryString = WXPayUtility.urlEncode(args); 65 if (!queryString.isEmpty()) { 66 uri = uri + "?" + queryString; 67 } 68 69 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 70 reqBuilder.addHeader("Accept", "application/json"); 71 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 72 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, null)); 73 reqBuilder.method(METHOD, null); 74 Request httpRequest = reqBuilder.build(); 75 76 // 发送HTTP请求 77 OkHttpClient client = new OkHttpClient.Builder().build(); 78 try (Response httpResponse = client.newCall(httpRequest).execute()) { 79 String respBody = WXPayUtility.extractBody(httpResponse); 80 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 81 // 2XX 成功,验证应答签名 82 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 83 httpResponse.headers(), respBody); 84 85 // 从HTTP应答报文构建返回数据 86 return WXPayUtility.fromJson(respBody, QueryEncryptBillEntity.class); 87 } else { 88 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 89 } 90 } catch (IOException e) { 91 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 92 } 93 } 94 95 private final String mchid; 96 private final String certificateSerialNo; 97 private final PrivateKey privateKey; 98 private final String wechatPayPublicKeyId; 99 private final PublicKey wechatPayPublicKey; 100 101 public GetSingleSubMchFundFlowBill(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 102 this.mchid = mchid; 103 this.certificateSerialNo = certificateSerialNo; 104 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 105 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 106 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 107 } 108 109 public static class GetSingleSubMchFundFlowBillRequest { 110 @SerializedName("sub_mchid") 111 @Expose(serialize = false) 112 public String subMchid; 113 114 @SerializedName("bill_date") 115 @Expose(serialize = false) 116 public String billDate; 117 118 @SerializedName("account_type") 119 @Expose(serialize = false) 120 public SubMchFundFlowBillAccountType accountType; 121 122 @SerializedName("algorithm") 123 @Expose(serialize = false) 124 public Algorithm algorithm; 125 126 @SerializedName("tar_type") 127 @Expose(serialize = false) 128 public TarType tarType; 129 } 130 131 public static class QueryEncryptBillEntity { 132 @SerializedName("download_bill_count") 133 public Long downloadBillCount; 134 135 @SerializedName("download_bill_list") 136 public List<EncryptBillEntity> downloadBillList; 137 } 138 139 public enum SubMchFundFlowBillAccountType { 140 @SerializedName("BASIC") 141 BASIC, 142 @SerializedName("OPERATION") 143 OPERATION, 144 @SerializedName("FEES") 145 FEES, 146 @SerializedName("DEPOSIT") 147 DEPOSIT 148 } 149 150 public enum Algorithm { 151 @SerializedName("AEAD_AES_256_GCM") 152 AEAD_AES_256_GCM, 153 @SerializedName("SM4_GCM") 154 SM4_GCM 155 } 156 157 public enum TarType { 158 @SerializedName("GZIP") 159 GZIP 160 } 161 162 public static class EncryptBillEntity { 163 @SerializedName("bill_sequence") 164 public Long billSequence; 165 166 @SerializedName("hash_type") 167 public HashType hashType; 168 169 @SerializedName("hash_value") 170 public String hashValue; 171 172 @SerializedName("download_url") 173 public String downloadUrl; 174 175 @SerializedName("encrypt_key") 176 public String encryptKey; 177 178 @SerializedName("nonce") 179 public String nonce; 180 } 181 182 public enum HashType { 183 @SerializedName("SHA1") 184 SHA1 185 } 186 187} 188
需配合微信支付工具库 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) 10 11func main() { 12 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 13 config, err := wxpay_utility.CreateMchConfig( 14 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 15 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 16 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 17 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 18 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 19 ) 20 if err != nil { 21 fmt.Println(err) 22 return 23 } 24 25 request := &GetSingleSubMchFundFlowBillRequest{ 26 SubMchid: wxpay_utility.String("19000000001"), 27 BillDate: wxpay_utility.String("2019-06-11"), 28 AccountType: SUBMCHFUNDFLOWBILLACCOUNTTYPE_BASIC.Ptr(), 29 Algorithm: ALGORITHM_AEAD_AES_256_GCM.Ptr(), 30 TarType: TARTYPE_GZIP.Ptr(), 31 } 32 33 response, err := GetSingleSubMchFundFlowBill(config, request) 34 if err != nil { 35 fmt.Printf("请求失败: %+v\n", err) 36 // TODO: 请求失败,根据状态码执行不同的处理 37 return 38 } 39 40 // TODO: 请求成功,继续业务逻辑 41 fmt.Printf("请求成功: %+v\n", response) 42} 43 44func GetSingleSubMchFundFlowBill(config *wxpay_utility.MchConfig, request *GetSingleSubMchFundFlowBillRequest) (response *QueryEncryptBillEntity, err error) { 45 const ( 46 host = "https://api.mch.weixin.qq.com" 47 method = "GET" 48 path = "/v3/bill/sub-merchant-fundflowbill" 49 ) 50 51 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 52 if err != nil { 53 return nil, err 54 } 55 query := reqUrl.Query() 56 if request.SubMchid != nil { 57 query.Add("sub_mchid", *request.SubMchid) 58 } 59 if request.BillDate != nil { 60 query.Add("bill_date", *request.BillDate) 61 } 62 if request.AccountType != nil { 63 query.Add("account_type", fmt.Sprintf("%v", *request.AccountType)) 64 } 65 if request.Algorithm != nil { 66 query.Add("algorithm", fmt.Sprintf("%v", *request.Algorithm)) 67 } 68 if request.TarType != nil { 69 query.Add("tar_type", fmt.Sprintf("%v", *request.TarType)) 70 } 71 reqUrl.RawQuery = query.Encode() 72 httpRequest, err := http.NewRequest(method, reqUrl.String(), nil) 73 if err != nil { 74 return nil, err 75 } 76 httpRequest.Header.Set("Accept", "application/json") 77 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 78 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), nil) 79 if err != nil { 80 return nil, err 81 } 82 httpRequest.Header.Set("Authorization", authorization) 83 84 client := &http.Client{} 85 httpResponse, err := client.Do(httpRequest) 86 if err != nil { 87 return nil, err 88 } 89 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 90 if err != nil { 91 return nil, err 92 } 93 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 94 // 2XX 成功,验证应答签名 95 err = wxpay_utility.ValidateResponse( 96 config.WechatPayPublicKeyId(), 97 config.WechatPayPublicKey(), 98 &httpResponse.Header, 99 respBody, 100 ) 101 if err != nil { 102 return nil, err 103 } 104 response := &QueryEncryptBillEntity{} 105 if err := json.Unmarshal(respBody, response); err != nil { 106 return nil, err 107 } 108 109 return response, nil 110 } else { 111 return nil, wxpay_utility.NewApiException( 112 httpResponse.StatusCode, 113 httpResponse.Header, 114 respBody, 115 ) 116 } 117} 118 119type GetSingleSubMchFundFlowBillRequest struct { 120 SubMchid *string `json:"sub_mchid,omitempty"` 121 BillDate *string `json:"bill_date,omitempty"` 122 AccountType *SubMchFundFlowBillAccountType `json:"account_type,omitempty"` 123 Algorithm *Algorithm `json:"algorithm,omitempty"` 124 TarType *TarType `json:"tar_type,omitempty"` 125} 126 127func (o *GetSingleSubMchFundFlowBillRequest) MarshalJSON() ([]byte, error) { 128 type Alias GetSingleSubMchFundFlowBillRequest 129 a := &struct { 130 SubMchid *string `json:"sub_mchid,omitempty"` 131 BillDate *string `json:"bill_date,omitempty"` 132 AccountType *SubMchFundFlowBillAccountType `json:"account_type,omitempty"` 133 Algorithm *Algorithm `json:"algorithm,omitempty"` 134 TarType *TarType `json:"tar_type,omitempty"` 135 *Alias 136 }{ 137 // 序列化时移除非 Body 字段 138 SubMchid: nil, 139 BillDate: nil, 140 AccountType: nil, 141 Algorithm: nil, 142 TarType: nil, 143 Alias: (*Alias)(o), 144 } 145 return json.Marshal(a) 146} 147 148type QueryEncryptBillEntity struct { 149 DownloadBillCount *int64 `json:"download_bill_count,omitempty"` 150 DownloadBillList []EncryptBillEntity `json:"download_bill_list,omitempty"` 151} 152 153type SubMchFundFlowBillAccountType string 154 155func (e SubMchFundFlowBillAccountType) Ptr() *SubMchFundFlowBillAccountType { 156 return &e 157} 158 159const ( 160 SUBMCHFUNDFLOWBILLACCOUNTTYPE_BASIC SubMchFundFlowBillAccountType = "BASIC" 161 SUBMCHFUNDFLOWBILLACCOUNTTYPE_OPERATION SubMchFundFlowBillAccountType = "OPERATION" 162 SUBMCHFUNDFLOWBILLACCOUNTTYPE_FEES SubMchFundFlowBillAccountType = "FEES" 163 SUBMCHFUNDFLOWBILLACCOUNTTYPE_DEPOSIT SubMchFundFlowBillAccountType = "DEPOSIT" 164) 165 166type Algorithm string 167 168func (e Algorithm) Ptr() *Algorithm { 169 return &e 170} 171 172const ( 173 ALGORITHM_AEAD_AES_256_GCM Algorithm = "AEAD_AES_256_GCM" 174 ALGORITHM_SM4_GCM Algorithm = "SM4_GCM" 175) 176 177type TarType string 178 179func (e TarType) Ptr() *TarType { 180 return &e 181} 182 183const ( 184 TARTYPE_GZIP TarType = "GZIP" 185) 186 187type EncryptBillEntity struct { 188 BillSequence *int64 `json:"bill_sequence,omitempty"` 189 HashType *HashType `json:"hash_type,omitempty"` 190 HashValue *string `json:"hash_value,omitempty"` 191 DownloadUrl *string `json:"download_url,omitempty"` 192 EncryptKey *string `json:"encrypt_key,omitempty"` 193 Nonce *string `json:"nonce,omitempty"` 194} 195 196type HashType string 197 198func (e HashType) Ptr() *HashType { 199 return &e 200} 201 202const ( 203 HASHTYPE_SHA1 HashType = "SHA1" 204) 205
应答参数
200 OK
download_bill_count 必填 integer
【下载信息总数】 下载信息总数
download_bill_list 选填 array[object]
【下载信息明细】 下载信息明细
属性 | |
bill_sequence 必填 integer 【账单文件序号】 账单文件序号,商户将多个文件按账单文件序号的顺序合并为完整的资金账单文件,起始值为1 hash_type 必填 string 【哈希类型】 哈希类型 可选取值
hash_value 必填 string(1024) 【哈希值】 原始账单(gzip需要解压缩)的摘要值,用于校验文件的完整性。GCM算法加密的账单解密成功表示校验完整性通过。 download_url 必填 string(2048) 【下载地址】 供下一步请求账单文件的下载地址,该地址5min内有效。 encrypt_key 必填 string(512) 【加密密钥】 加密账单文件使用的加密密钥。密钥用商户证书的公钥进行加密,然后进行Base64编码 nonce 必填 string(16) 【随机字符串】 加密账单文件使用的随机字符串 |
应答示例
200 OK
1{ 2 "download_bill_count" : 1, 3 "download_bill_list" : [ 4 { 5 "bill_sequence" : 1, 6 "hash_type" : "SHA1", 7 "hash_value" : "79bb0f45fc4c42234a918000b2668d689e2bde04", 8 "download_url" : "https://api.mch.weixin.qq.com/v3/bill/downloadurl?token=xxx", 9 "encrypt_key" : "a0YK7p+9XaKzE9N4qtFfG/9za1oqKlLXXJWBkH+kX84onAs2Ol/E1fk+6S+FuBXczGDRU8I8D+6PfbwKYBGm0wANUTqHOSezzfbieIo2t51UIId7sP9SoN38W2+IcYDviIsu59KSdyiL3TY2xqZNT8UDcnMWzTNZdSv+CLsSgblB6OKGN9JONTadOFGfv1OKkTp86Li+X7S9bG62wsa572/5Rm4MmDCiKwY4bX2EynWQHBEOExD5URxT6/MX3F1D3BNYrE4fUu1F03k25xVlXnZDjksy6Rf3SCgadR+Cepc6mdfF9b2gTxNsJFMEdYXbqL0W1WQZ3UqSPQCguK6uLA==", 10 "nonce" : "a8607ef79034c49c" 11 } 12 ] 13} 14
错误码
公共错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
业务错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | INVALID_REQUEST | 参数错误 | 请检查bill_date,仅支持下载3个月以内的资金流水账单 |
400 | NO_STATEMENT_EXIST | 请求的账单文件不存在 | 请检查二级商户在指定日期是否有资金操作 |
400 | STATEMENT_CREATING | 账单生成中 | 请先检查二级商户在指定日期内是否有资金操作,若有,则在T+1日上午10点后再重新下载 |
403 | NO_AUTH | 权限异常 | 请检查sub_mchid是否为服务商的子商户 |
403 | NO_AUTH | 权限异常 | 请电商平台在产品中心开通下载二级商户资金账单产品权限 |
429 | FREQUENCY_LIMITED | 请求过于频繁 | 请降低调用频率 |