Login expired. Please log in again.




Submitted successfully



Network exception, please try again later


Uploading Image API

Public API
Uploading Image
Help Center
Contact Us

Uploading Image API

Latest update time:2019.09.09 Release notes

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.

API Intro

Request Url: https://api.mch.weixin.qq.com/secapi/mch/uploadmedia

Request method:POST

Certificate Requirements:Yes Certificate is required.

Parameter Settings

Name Variable Name Type Required Description
Merchant ID mch_id string[1,32] Yes Merchant ID assigned by WeChat Pay
Media File media string[1,256] Yes fThe media file content in form-data, including filename, filelength, content-type, etc. This field will not be used to generate the signature
Hash value of media file content media_hash string[1,32] Yes The MD5 value of media content
Signature sign string[1,32] Yes Signature, please refer to Security Specifications for the detailed signature algorithm
Sign type sign_type string[1,10] No MD5 as default


curl --cert ./apiclient_cert.pem --key ./apiclient_key.pem -F 'mch_id=1000000000' -F 'media_hash=709d1e858d2ef9d0501cc053668b2872' -F 'sign=D675A1E471DBF7C0B1AC5883B5BDA9EF' -F 'media=@test.jpg' https://api.mch.weixin.qq.com/secapi/mch/uploadmedia

// 参考上述指引说明,并引入 `MediaUtil` 正常初始化,无额外条件
use WechatPay\GuzzleMiddleware\Util\MediaUtil;
// 实例化一个媒体文件流,注意文件后缀名需符合接口要求
$media = new MediaUtil('/your/file/path/with.extension');

// 正常使用Guzzle发起API请求
try {
    $resp = $client->request('POST', 'https://api.mch.weixin.qq.com/v3/[merchant/media/video_upload|marketing/favor/media/image-upload]', [
        'body'    => $media->getStream(),
        'headers' => [
            'Accept'       => 'application/json',
            'content-type' => $media->getContentType(),
    // POST 语法糖
    $resp = $client->post('merchant/media/upload', [
        'body'    => $media->getStream(),
        'headers' => [
            'Accept'       => 'application/json',
            'content-type' => $media->getContentType(),
    echo $resp->getStatusCode().' '.$resp->getReasonPhrase()."\n";
    echo $resp->getBody()."\n";
} catch (Exception $e) {
    echo $e->getMessage()."\n";
    if ($e->hasResponse()) {
        echo $e->getResponse()->getStatusCode().' '.$e->getResponse()->getReasonPhrase()."\n";
        echo $e->getResponse()->getBody();

Return Data

Name Variable Name Type Required Description
Return Status Code return_code string[1,16] Yes SUCCESS/FAIL
Specifies communicating label instead of transaction label. The status of the transaction is determined by the value of the result_code field. 
Return Data return_msg string[1,128] No If not empty, the returned info is the error description. Signature failure Parameter format checking error 
Example:Signature failure

If return_code is SUCCESS, return data will also include the following fields:

Name Variable Name Type Required Description
Service Result result_code string[1,32] Yes SUCCESS/FAIL
Media ID media_id string[1,256] Yes The media file content ID returned by WeChat Pay
Example:9UYfXi- WMUhgWXvJtEw4_gBl e_EfrD_pIL0bS8GAsK8
Signature sign string[1,32] Yes Specifies a signature.
Error Code err_code string[1,32] No Error code
Error Code Description err_code_de s string[1,128] No Detailed description of error code
Example:Sub merchant information error, please check and retry


<media_id><![CDATA[9UYfXi- WMUhgWXvJtEw4_gBle_EfrD_pIL0bS8GAsK8]]></media_id>


Error Code

Error Code Description Reason Solution
INVALID_REQUEST HTTP GET method not supported Use POST method. Check and call again. Debugging by developer
INVALID_REQUEST Invalid XML format Invalid XML format. Check and call again. Invalid XML format. Check and call again.
SIGNERROR Signature validation Signature validation failed. Check and try again. Signature validation failed. Check and try again.
INVALID_REQUEST Certificate is required Getting certificate serial number is failed.
Certificate verification is failed.
Check the certificate
PARAM_ERROR Regular Validation XXX has invalid format. Check and try again. Automated checks and filters
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.
Please check the image
PARAM_ERROR Merchant ID error The merchant ID is wrong, please check Please check the merchant ID
INVALID_REQUEST Entry permissions No permissions. Check and try again. Check permissions
Frequency limit Operation is too fast, please retry later Please reduce the API call frequency
SYSTEMERROR System error occurred when viewing a sub-vendor System error occurred when viewing a sub-vendor. Try again later. Contact WeChat Pay Support

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2019 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

Wechat Pay Global