部分微信支付业务指定商户需要使用图片上传 API来上报图片信息，从而获得必传参数的值：图片MediaID 。
接口说明
请求方式：【POST】/v3/merchant/media/upload
请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ，指引点击查看
请求主体类型： multipart/form-data
字段说明
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为multipart/form-data
body 包体参数
file 必填 message
【图片文件】将媒体图片进行二进制转换，得到的媒体图片二进制内容，在请求body中上传此二进制内容。媒体图片只支持JPG、BMP、PNG格式，文件大小不能超过2M。
meta 必填 Object
【媒体文件】媒体文件元信息，使用json表示，包含两个对象：filename、sha256。
 | 属性 |
| filename 必填 string(128) 【文件名称】 商户上传的媒体图片的名称，商户自定义，必须以JPG、BMP、PNG为后缀。
sha256 必填 string(64) 【文件摘要】 图片文件的文件摘要，即对图片文件的二进制内容进行sha256计算得到的值。 |
请求示例
示例代码
1String filePath = "/your/home/hellokitty.png";
2URI uri = new URI("https://api.mch.weixin.qq.com/v3/merchant/media/upload");
3File file = new File(filePath);
4try (FileInputStream ins1 = new FileInputStream(file)) {
5 String sha256 = DigestUtils.sha256Hex(ins1);
6 try (InputStream ins2 = new FileInputStream(file)) {
7 HttpPost request = new WechatPayUploadHttpPost.Builder(uri)
8 .withImage(file.getName(), sha256, ins2)
9 .build();
10 CloseableHttpResponse response1 = httpClient.execute(request);
11 }
12}
PHP
1
2use WechatPay\GuzzleMiddleware\Util\MediaUtil;
3
4$media = new MediaUtil('/your/file/path/with.extension');
5
6try {
7 $resp = $client->request('POST', 'https://api.mch.weixin.qq.com/v3/merchant/media/upload', [
8 'body' => $media->getStream(),
9 'headers' => [
10 'Accept' => 'application/json',
11 'content-type' => $media->getContentType(),
12 ]
13 ]);
14
15 $resp = $client->post('v3/merchant/media/upload', [
16 'body' => $media->getStream(),
17 'headers' => [
18 'Accept' => 'application/json',
19 'content-type' => $media->getContentType(),
20 ]
21 ]);
22 echo $resp->getStatusCode().' '.$resp->getReasonPhrase()."\n";
23 echo $resp->getBody()."\n";
24} catch (Exception $e) {
25 echo $e->getMessage()."\n";
26 if ($e->hasResponse()) {
27 echo $e->getResponse()->getStatusCode().' '.$e->getResponse()->getReasonPhrase()."\n";
28 echo $e->getResponse()->getBody();
29 }
30 return;
31}
应答字段
media_id 必填 string(512)
【媒体文件标识ID】 微信返回的媒体文件标识ID。
应答示例
200 OK
1{
2"media_id": "H1ihR9JUtVj-J7CJqBUY5ZOrG_Je75H-rKhTG7FUmg9sxNTbRN54dFiUHnhg
3rBQ6EKeHoGcHTJMHn5TAuLVjHUQDBInSWXcIHYXOeRa2OHA"
4}请求步骤
图片上传步骤
1. 创建一个POST的方法请求/upload URI
例如： POST https://api.mch.weixin.qq.com/v3/merchant/media/upload HTTP/1.1
2. 将文件的数据添加到请求主体
媒体图片二进制内容，放在请求HTTP的body中。
2.2. 媒体文件元信息meta参数的获取方式说明：
媒体文件元信息，使用json表示，包含两个对象：filename、sha256。
商户上传的媒体图片的名称，商户自定义，必须以JPG、BMP、PNG为后缀。
图片文件的文件摘要，即对图片文件的二进制内容进行sha256计算得到的值。
{ "filename": "filea.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }
1POST
2/v3/merchant/media/upload
31566987169 //时间戳
412ced2db6f0193dda91ba86224ea1cd8 //随机数
5{"filename":"filea.jpg","sha256":"hjkahkjsjkfsjk78687dhjahdajhk"}3. 添加HTTP头
1Content-Type：multipart/form-data.设置为要上载的对象的MIME媒体类型。
2Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900231671",
3nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",timestamp="1567067659",
4serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
5signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7SFR+BjDZh6
689hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPNQ7dBLO7ux6MoSuQp69
7PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e7hwUbDwGln170ZXomoO1KpQSbw3f1u
8WUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M7aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
9Content-Type: multipart/form-data;boundary=boundary4. 添加body
4. 添加body
1// 以下为body的内容
2--boundary // boundary为商户自定义的一个字符串
3Content-Disposition: form-data; name="meta";
4Content-Type: application/json
5//此处必须有一个空行
6{ "filename": "filea.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }
7--boundary
8Content-Disposition: form-data; name="file"; filename="filea.jpg";
9Content-Type: image/jpg
10//此处必须有一个空行
11pic1 //pic1即为媒体图片的二进制内容
12--boundary-- | 请求包体每行结尾都需要包含\r\n（空行也需要）。 |
|
5.发送请求
1POST /v3/merchant/media/upload HTTP/1.1
2Host: api.mch.weixin.qq.com
3Authorization: WECHATPAY2-SHA256-RSA2048
4mchid="1900231671",nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",
5timestamp="1567067659",
6serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
7signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7
8SFR+BjDZh689hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPN
9Q7dBLO7ux6MoSuQp69PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e
107hwUbDwGln170ZXomoO1KpQSbw3f1uWUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M
117aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
12Content-Type: multipart/form-data;boundary=boundary
13--boundary
14Content-Disposition: form-data; name="meta";
15Content-Type: application/json
16{ "filename": "filea.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }
17--boundary
18Content-Disposition: form-data; name="file"; filename="filea.jpg";
19Content-Type: image/jpg
20pic1
21--boundary--错误码
公共错误码
|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常，请稍后重试 | 请稍后重试 |
业务错误码
|
500 | SYSTEM_ERROR | 系统错误 | 系统异常，请使用相同参数稍后重新调用 |
500 | SYSTEM_ERROR | 文件系统错误，请稍后重试 | 文件系统异常，请使用相同参数稍后重新调用 |
400 | PARAM_ERROR | 图片文件名称不正确，请检查后重新提交 | 图片文件名称不正确，只支持jpg，jpeg，png，bmp，请使用正确图片文件重新调用 |
400 | PARAM_ERROR | 文件二进制内容不是图片，请检查后重新提交 | 上传文件二进制内容头部不正确，只支持jpg，jpeg，png，bmp，请使用正确图片文件重新调用 |
400 | PARAM_ERROR | 图片sha256值有误，请检查后重新提交 | 图片sha256值计算有误，请检查算法，重新计算后提交 |
400 | PARAM_ERROR | 文件大小不能超过2M，请检查后重新提交 | 商户更换文件或者对图片进行压缩后，重新调用 |
400 | PARAM_ERROR | 文件为空，请检查后重新提交 | 商户更换文件后，重新调用 |
429 | FREQUENCY_LIMIT_EXCEED | 操作过快，请稍后重试 | 请商户降低每秒调用频率 |
429 | FREQUENCY_LIMIT_EXCEED | 当天上传文件数已达上限 | 请商户降低每天调用频率 |
403 | NO_AUTH | 商户权限异常 | 请确认是否已经开通相关权限 |
