Upload File

Update Time：2025.01.07

Some designated merchants of Weixin Pay overseas business need to upload documents. They can use this API to submit these documents and obtain the FileID values required by other business APIs.

1. API Instructions

Applicable to：Common mode Institutional mode

Request URL：https://apihk.mch.weixin.qq.com/v3/global/merchant-storage/file/upload

Request body type：multipart/form-data

Request method：POST

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

Name

Variable Name

Type

Required

Description

File information

file

object

Yes

Body performs binary conversion for the file to obtain binary content, which is uploaded in the request body. The file can be in the PDF, JPG, BMP, or PNG format, with a file size not exceeding 5 M.

File information

File meta information

3. Request Sample of Each Language

---Sample code to be updated---

4. Return Parameters

Name	Variable Name	Type	Required	Description
File ID	file_id	string[16, 64]	Yes	File ID returned by WeChat Example：b6a17e2a-1dc4-4376-8630-e73d06490c0d

Return Example

Normal example

1{
2  "file_id": "b6a17e2a-1dc4-4376-8630-e73d06490c0d"
3}

5. Request Procedure

5.1. Create a POST method request

For example：

HTTP

1POST https://apihk.mch.weixin.qq.com/v3/global/merchant-storage/file/upload HTTP/1.1

5.2.Add the file data to the request body

5.2.1 How to obtain the file parameters of the file information:
Conduct binary conversion to the file to obtain the binary content and place it in the http.

5.2.2 How to obtain the meta parameters of the file meta information：
The file meta information is indicated using json, involving two objects: filename and digest.
● How to obtain the filename parameter：
The name of the file uploaded by the merchant is determined by the merchant and must be suffixed using pdf, jpg, bmp, or png
● How to obtain the digest parameter:
File digest, that is, the value obtained by sha256 calculation of the binary content of the uploaded file

5.2.3 Signature calculation:：
Signature generation
The request body involved in signature calculation is a JSON string of meta：
{"filename": "file1.pdf", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"}

Example of a string to be signed：

1POST
2/v3/global/merchant-storage/file/upload
31566987169           // Timestamp
412ced2db6f0193dda91ba86224ea1cd8   // Random number
5{"filename": "file1.pdf", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"}

5.3.Add the HTTP head：

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": "file1.pdf", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"} 
7--boundary
8Content-Disposition: form-data; name="file"; filename="file1.pdf";
9Content-Type: application/pdf
10//There must be a blank line here
11context123    //context123 is the binary content of the file to be uploaded
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/global/merchant-storage/file/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": "file1.pdf", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"} 
19--boundary
20Content-Disposition: form-data; name="file"; filename="file1.pdf";
21Content-Type: application/pdf
22
23context123
24--boundary--

6. Error Code

Error Codes	Error Message	Description	Solution
400	INVALID_REQUEST	The file size of the uploaded file cannot exceed 5 M. Please check the size of the transmitted field (content).	Please replace or compress the file before calling it again.
400	INVALID_REQUEST	The value of the uploaded file content calculated by sha256 encryption algorithm is inconsistent with the value of the transmitted field (digest). Please check the calculation method of the transmitted field (digest).	Please refer to the guidelines to check the calculation method of the transmitted field (digest)
400	INVALID_REQUEST	The file type of uploaded file is currently not supported	Check whether the transmitted field (content_type) is in pdf, jpg, bmp, or png