Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Downloading Platform Certificate API

Latest update time:2020.04.30 Release notes


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.

Note:

Instructions:

1. 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.

2. 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.

3. 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.

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

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


Best practice:

1. Call the API on the central control server list.

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

3. 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.

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


API Intro

Request URL: https://api.mch.weixin.qq.com/hk/v3/certificates

Request method: GET

Applicable object:Common modeInstitutional mode

API Rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3


path This parameter needs to be set at the request URL

query This parameter needs to be set at the JSON for request body

Request Parameters

None


Returned Result

Response for failed request

Name Variable Name Type Required Description
Returned status code code string(32) Yes Error code. See the error code list for the enumerated values.
Example:INVALID_REQUEST
Returned information message string(256) Yes Returned message. It indicates the reason for the error if not empty.
Example:Parameter format verification error
+ Detailed error description detail object No It is returned when code is PARAM_ERROR. Details will be described below.
Name Variable Name Type Required Description
Location of the incorrect parameter field string(256) Yes Enter the JSON Pointer pointing to the invalid parameter when it is in the JSON of the request body;
enter the variable name of the parameter when the invalid parameter is in the request URL or querystring.
Example:#/properties/payer
Value of the incorrect parameter value string(256) Yes Value of the incorrect parameter
Example:1346177081915535577
Cause of error issue string(256) Yes Cause of error
Example:It is different from ALLOF schema
Location of the incorrect parameter location string(256) No body:The incorrect parameter is in the JSON for request body
url:The incorrect parameter is in the request URL
query:The incorrect parameter is in the querystring of the request
Example:body

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.
Name Variable Name Type Required Description
Algorithm of encrypted certificate algorithm string(32) Yes Certificate encryption algorithm, with the key of API KEY, which needs to be set on the merchant platform.
Example:AEAD_AES_256_GCM
Random string of the encrypted certificate nonce string(12) Yes Random string of encrypted certificate
Example:61f9c719728a
Additional data of encrypted certificate associated_data string(32) Yes Fixed value: certificate
Example:certificate
Encrypted certificate content ciphertext string(344) Yes With the API KEY and the above parameters, you can decrypt the plaintext of the platform certificate.The certificate plaintext is in PEM format.(Note:
he certificate expiration time in PEM format may be inconsistent with the certificate deprecation time returned by the API when the certificate is replaced.)
Example:Y1IPF0kyRe+aJ7TK6cw08r1g/agxl16o

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.


Note: For the API information of the "AEAD_AES_256_GCM" algorithm, see [rfc5116].


For example:

{
    "data": [
        {
            "serial_no": "5157F09EFDC096DE15EBE81A47057A7232F1B8E1",
            "effective_time ": "2018-06-08T10:34:56+08:00",
            "expire_time ": "2018-12-08T10:34:56+08:00",
            "encrypt_certificate": {
                "algorithm": "AEAD_AES_256_GCM",
                "nonce": "61f9c719728a",
                "associated_data": "certificate",
                "ciphertext": "sRvt… "
            }
        },
        {
            "serial_no": "50062CE505775F070CAB06E697F1BBD1AD4F4D87",
            "effective_time ": "2018-12-07T10:34:56+08:00",
            "expire_time ": "2020-12-07T10:34:56+08:00",
            "encrypt_certificate": {
                "algorithm": "AEAD_AES_256_GCM",
                "nonce": "35f9c719727b",
                "associated_data": "certificate",
                "ciphertext": "aBvt… "
            }
        }
    ]
}
{
"code":"INVALID_REQUEST",
"message":"Parameter format verification error",
"detail":{
    "field":"#/properties/payer",
    "value":"1346177081915535577",
    "issue":"It is different from ALLOF schema",
    "location":"body"
   }
}

Error Codes

Name Description Solution
SYSTEMERROR System error System error. Please call the API again to initiate the query.


Release notes

close
V1.0
2020.04.30
1.Downloading Platform Certificate API released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2019 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

Wechat Pay Global

ICP证

粤B1.B2-20090295