Downloading Platform Certificate

Update Time:2025.01.07

WeChat Pay will change the platform certificate from time to time due to certificate validity and for transaction security. WeChat Pay provides a range of APIs to help merchant backend system replace the certificate easily.

Tips:

Instructions:

  • It is recommended that developers use the central control server (i.e., unified management and distribution. Pay attention to the confidentiality and security of the certificate) to uniformly download and manage the WeChat Pay platform certificate. Other service logic servers conduct the signature verification and decryption of messages via the central control server.

  • Before WeChat Pay replaces the platform certificate, the certificate to be replaced will be added to the merchant's platform certificate list 24 hours in advance. The central control server needs to view the merchant's platform certificate list periodically and download the latest platform certificate in time.

  • When WeChat Pay replaces the platform certificate, different certificate serial numbers may exist in response requests and callback notifications received by the merchant, and the merchant should process it properly.

  • Rate limit rules for the API obtaining platform certificates: For a single Merchant ID, it is 1000/s.

  • For sensitive information encryption, it is recommended to use the latest platform certificate (that is, a certificate with a longer valid period).

 

Best practice:

  • Call the API on the central control server list.

  • Call regularly, with an interval of less than 12 hours.

  • Compare with the local certificate serial number list. A new certificate serial number indicates a certificate to be replaced.The old certificate needs to be cleaned up before being deprecated.

  • After obtaining the certificate, distribute it to each service API server.


1. API intro

Applicable object: Common mode Institutional mode

Request URL: https://apihk.mch.weixin.qq.com/v3/global/certificates

Request method: GET

 

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

None

3. Response Parameters

Response for successful request:

Name

Variable Name

Type

Required

Description

Certificate serial number

serial_no

string(40)

Yes

Serial numbers of certificates
Example: 5157F09EFDC096DE15EBE81A47057A7232F1B8E1

Certificate enabling time

effective_time

string(32)

Yes

The time when the certificate took effect, in RFC3339 format. The enabling time for each platform certificate is fixed.
Example: 2018-06-08T10:34:56+08:00

Certificate deprecation time

expire_time

string(32)

Yes

The time when the certificate expired, in RFC3339 format.
Before replacing the platform certificate, the deprecation time of the old certificate will be modified 24 hours in advance, and the API returns both the new and the old platform certificates. After the replacement is complete, the API returns the latest platform certificate.
Example: 2018-06-08T10:34:56+08:00

Certificate information

encrypt_certificate

object

Yes

Certificate information. For more information, see the description below.

Certificate information

he procedure of how to decrypt the certificate is described as follows.

  1. Obtain the merchant's key from the merchant platform and record it as "key".

  2. For the algorithm described in "algorithm" (which is AEAD_AES_256_GCM), obtain the corresponding parameters "nonce" and "associated_data".

  3. Use "key", "nonce" and "associated_data" to decrypt "ciphertext" (decode ciphertext with base64 before decrypting) to get the certificate content.

Tips:

For the API information of the "AEAD_AES_256_GCM" algorithm, seerfc5116

Response for failed request:

Name

Variable Name

Type

Required

Description

Returned status code

code

string[1,32]

Yes

Error code. See the error code list for the enumerated values.

Returned information

message

string[1,256]

Yes

Returned message. It indicates the reason for the error if not empty.

Detailed error description

detail

object

No

It is returned when code is PARAM_ERROR. Details will be described below.

Detailed error description

Response Example:

SUCCESS

1{
2	"data": [{
3			"serial_no": "5157F09EFDC096DE15EBE81A47057A7232F1B8E1",
4			"effective_time ": "2018-06-08T10:34:56+08:00",
5			"expire_time ": "2018-12-08T10:34:56+08:00",
6			"encrypt_certificate": {
7				"algorithm": "AEAD_AES_256_GCM",
8				"nonce": "61f9c719728a",
9				"associated_data": "certificate",
10				"ciphertext": "sRvt… "
11			}
12		},
13		{
14			"serial_no": "50062CE505775F070CAB06E697F1BBD1AD4F4D87",
15			"effective_time ": "2018-12-07T10:34:56+08:00",
16			"expire_time ": "2020-12-07T10:34:56+08:00",
17			"encrypt_certificate": {
18				"algorithm": "AEAD_AES_256_GCM",
19				"nonce": "35f9c719727b",
20				"associated_data": "certificate",
21				"ciphertext": "aBvt… "
22			}
23		}
24	]
25}

ERROR

1{
2	"code": "INVALID_REQUEST",
3	"message": "Parameter format verification error",
4	"detail": {
5		"field": "#/properties/payer",
6		"value": "1346177081915535577",
7		"issue": "与ALLOF schema不符",
8		"location": "body"
9	}
10}

 

4. Error Codes

Error Message

Description

Solution

SYSTEM_ERROR

System error

System error. Please call the API again to initiate the query.

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.