Merchants or institutions call this API to upload the certificate images in jpeg, jpg, bmp, png format. The API should be called through POST form, with enctype set as multipart/form-data.
1. API Instructions
Applicable to:Common mode Institutional mode
Request URL:https://apihk.mch.weixin.qq.com/v3/merchant/media/upload
Request body type:multipart/form-data
Path parameter is a path parameter.
Query parameter needs to be passed in the request URL.
Body parameter needs to be passed in the request JSON.
2. Request Parameters
|
File information | file | object | Yes | Body Binary conversion of the media image to obtain the binary content of the media image, upload the binary content in the request body. Media images only support JPG, BMP, and PNG formats, and the file size cannot exceed 2M Example:pic1 |
Media file meta information | meta | object | Yes | Body Media file meta information, expressed in json, contains two objects: filename and sha256. |
 | Media file meta information | | |
File name | filename | string[1, 128] | Yes | The name of the media image uploaded by the merchant is customized by the merchant and must be suffixed with JPG, BMP, and PNG. Example:verify.jpg | Document summary | sha256 | string[1, 64] | Yes | The file summary of the picture file is the value obtained by sha256 calculation of the binary content of the picture file Example:ff3f4036a1164d1ddbad5b3edf9022addb3e1961a54a922708a6c1ffc49e5489 |
|
|
3. Request examples with different development languages
JAVA

1String filePath = "/your/home/hellokitty.png";
2URI uri = new URI("https://apihk.mch.weixin.qq.com/v3/merchant/media/upload");
3File file = new File(filePath);
4
5try (FileInputStream ins1 = new FileInputStream(file)) {
6 String sha256 = DigestUtils.sha256Hex(ins1);
7 try (InputStream ins2 = new FileInputStream(file)) {
8 HttpPost request = new WechatPayUploadHttpPost.Builder(uri)
9 .withImage(file.getName(), sha256, ins2)
10 .build();
11 CloseableHttpResponse response1 = httpClient.execute(request);
12 }
13}
PHP

1
2use WechatPay\GuzzleMiddleware\Util\MediaUtil;
3
4$media = new MediaUtil('/your/file/path/with.extension');
5
6
7try {
8 $resp = $client->request('POST', 'https://apihk.mch.weixin.qq.com/v3/[merchant/media/video_upload|marketing/favor/media/image-upload]', [
9 'body' => $media->getStream(),
10 'headers' => [
11 'Accept' => 'application/json',
12 'content-type' => $media->getContentType(),
13 ]
14 ]);
15
16 $resp = $client->post('merchant/media/upload', [
17 'body' => $media->getStream(),
18 'headers' => [
19 'Accept' => 'application/json',
20 'content-type' => $media->getContentType(),
21 ]
22 ]);
23 echo $resp->getStatusCode().' '.$resp->getReasonPhrase()."\n";
24 echo $resp->getBody()."\n";
25} catch (Exception $e) {
26 echo $e->getMessage()."\n";
27 if ($e->hasResponse()) {
28 echo $e->getResponse()->getStatusCode().' '.$e->getResponse()->getReasonPhrase()."\n";
29 echo $e->getResponse()->getBody();
30 }
31 return;
32}
Request examples with Java, please refer to:wechatpay-apache-httpclient
Request examples with PHP, please refer to:wechatpay-guzzle-middleware
4. Return Parameters
|
Media file ID | media_id | string[1, 512] | Yes | Id of the media file returned by WeChat. Example:b6a17e2a-1dc4-4376-8630-e73d06490c0d |
Return Example
Normal example

1{
2 "media_id": "6uqyGjvHzOhsLleGFQVRF"
3}
5. Request Procedure
5.1. Create a POST method request/upload URI
HTTP

1POST https://apihk.mch.weixin.qq.com/v3/merchant/media/upload HTTP/1.1
5.2.Add the file data to the request body
5.2.1 How to obtain the file parameter of an image:
The binary content of an image is included in the body of the request HTTP.
5.2.2 How to obtain the meta parameter of a media file:
Media file meta information, expressed in JSON, contains two objects: filename and sha256.
● How to obtain the filename parameter:
The custom name of an image uploaded by the merchant and must be suffixed with ".JPG", ".BMP", or ".PNG".
● How to obtain the sha256 parameter:
The image digest, obtained by calculating the binary content of an image with sha256.
5.2.3 Signature calculation::
Signature generation
The request body involved in signature calculation is a JSON string of meta:
{"filename": "filea.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"}
Example of a string to be signed:

1POST
2/v3/merchant/media/upload
31566987169 // Timestamp
412ced2db6f0193dda91ba86224ea1cd8 // Random number
5{"filename": "file1.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"}

1Content-Type:multipart/form-data.Set to the MIME media type of the object to be uploaded.
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=="
9
10Content-Type: multipart/form-data;boundary=boundary
5.4.Add a body:

1// The content of the body is as follows
2--boundary // boundary is a string customized by the merchant
3Content-Disposition: form-data; name="meta";
4Content-Type: application/json
5//There must be a blank line here
6{ "filename": "filea.jpg", "sha256": " hjkahkjsjkfsjk78687dhjahdajhk " }
7--boundary
8Content-Disposition: form-data; name="file"; filename="filea.jpg";
9Content-Type: image/jpg
10//There must be a blank line here
11pic1 //pic1 is the binary content of an image.
12--boundary--
Note:The end of each line of the request packet body needs to contain \r\n (including the blank lines).
5.5.Send request

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
14--boundary
15Content-Disposition: form-data; name="meta";
16Content-Type: application/json
17
18{ "filename": "filea.jpg", "sha256": " hjkahkjsjkfsjk78687dhjahdajhk " }
19--boundary
20Content-Disposition: form-data; name="file"; filename="filea.jpg";
21Content-Type: image/jpg
22
23pic1
24--boundary--
6. Error Code
|
500 | SYSTEMERROR | System error | System error occurred when viewing a sub-vendor. Try again later. |
400 | PARAM_ERROR | Regular Validation | XXX has invalid format. Check and try again. |
PARAM_ERROR | Image format error | The image format is wrong, please check and retry. The image size should be less than 2M. Image Hash value error, please check and retry. |
PARAM_ERROR | FIle exceed the size limit | FIle is bigger than 2M |
429 | FREQUENCY_LIMIT_EXCEED | Frequency limit | Operation is too fast, please retry later |
403 | NO_AUTH | No permissions to call this endpoint | No permissions. Check and try again. |