1. Background Introduction

WeChat Pay uses HTTPS to ensure communication security. Before communicating with the WeChat Pay server, partners need to deploy the root certificate of an authority in the client’s operating system or execution environment (such as JRE). During the process of partners calling the WeChat Pay API, the authenticity of the WeChat Pay server and domain name will be verified by root certificates. Affected by the latest trust policy of Mozilla’s root certificate trust store (All globally trusted CA root certificates are required to be replaced at least every 15 years after generation. Trusted roots that exceed this time will gradually be stopped trusting by Mozilla), DigiCert will gradually discontinue the issuance of TLS/SSL certificates using the old root system (G1) and start using the new root system (G2) to issue TLS/SSL certificates. The current root issuing CA for WeChat Pay server certificates is Digicert Global Root CA (G1). WeChat Pay plans to gradually enable new server certificates issued by DigiCert Global Root G2 starting from 0:00 on September 20, 2024. Merchants’ technical teams should carefully read this guideline and complete the relevant verification and correction to avoid affecting normal transactions.

Note:

1. Partners need to refer to the guidelines and complete the relevant verification and correction before 0:00 on September 20, 2024.
2. Most operating systems and execution environments have built in the DigiCert Global Root G2 root certificate by default, so most systems do not need to be modified to be compatible with the new server certificate. However, if a partner’s server/terminal device does not have a built-in G2 root certificate, or if the program code specifies the use of the old G1 root certificate, it will be affected, resulting to service interruptions. Please promptly remove the specified old root certificate operations, use the system’s built-in trust store for verification, and ensure that you have the DigiCert Global Root G2 root certificate;
3. The new G2 root system uses a higher security SHA256 signature algorithm and remains compatible with current mainstream operating systems and mobile devices. Compatibility in mainstream environments is as follows:
   

For corresponding root certificate files, please refer to:

Baltimore CyberTrust Root: Download PEM, Download DER/CRT

Digicert Global Root CA: Download PEM , Download DER/CRT

Digicert Global Root G2: Download PEM, Download DER/CRT

2. Partner Notice

Partners need to confirm that the systems or terminal devices linked up with WeChat Pay are compatible with the new server certificate, and follow the methods in the “Verification Guidelines” section to complete the verification before 0:00 on September 20, 2024:

• If the verification results are normal, partners do not need to take any further action
• If the verification results are abnormal, partners need to modify the relevant system implementation or configuration, and must complete the corrections no later than 0:00 on September 20, 2024. Otherwise, communication via HTTPS between the partner’s business system and WeChat Pay system will not function properly, which will affect the payment services.

If partners encounter issues during the verification and correction process, they can post inquiries in the WeChat group or send e-mail to wxp_globalts@tencent.com, and we will have a dedicated person to provide solutions and replies.

3. Verification Guidelines

Verification method: Bind host, and make a request to the WeChat Pay server with the newly deployed certificate

Partners can bind the IPs by modifying the hosts file of the operating system. For example, you can add a line in the hosts file like the following to bind the domain name “http://apihk.mch.weixin.qq.com/” to the new certificate environment:

43.142.224.50 apihk.mch.weixin.qq.com

In Linux systems, the full path of the hosts file is “/etc/hosts”; and in Windows systems, the full path of the hosts file is “C:\Windows\System32\drivers\etc\hosts”.

Partners should modify the hosts file configuration based on the actual domain name used for linking up. The corresponding relation between the host and IP for the verification environment with the newly deployed server certificate is as follows:

Note:

1. The interfaces that can be accessed by the host environment are completely consistent with the production environment and are truly effective, and are considered as producing formal business. Before verification, please assess the impact on your business system and operations thoroughly;
2. After verification is complete, promptly restore the host configuration on the server. Once the WeChat Pay server certificate update is complete, the IP used here will be shut down;
3. Verification should be conducted using the same operating system, execution environment, development language, and program logic as in the production environment. Successful verification using command-line tools like curl does not necessarily mean that your system supports the new server certificate;
4. Verify all WeChat Pay interfaces being used one by one. If they all function properly, it means your system supports the new WeChat Pay server certificate. Otherwise, you need to identify and correct issues based on the correction guidelines.

4. Correction Guidelines

In most cases, verification failure is caused by the following two situations:

Scenario 1: The program specifies a root certificate, but the specified root certificate only includes the old G1 root certificate.

Scenario 2: The new G2 root certificate is not deployed on the server.

You can correct this using the following two solutions:

Solution 1: Delete the code specifying the root certificate. When the program does not specify a root certificate, the system’s built-in root certificate will be used. Most systems already include the new G2 root certificate, so deleting the code specifying the root certificate will not affect your existing business.

Solution 2: Update the root certificate. Append the new G2 root certificate to the truststore or root certificate trust file (Note: When appending the new root certificate, ensure to retain the old G1 root certificate).

It is recommended to use “Solution 1” for correction as it provides better compatibility. The reason is: The new G2 root certificate will no longer be trusted by Mozilla on April 15, 2029, and will need to be replaced with a new root certificate at that time. By using Solution 1 for the correction, your system probably already includes the subsequent root certificates that need to be used, thus avoiding any impact. If you use Solution 2 for correction, you may still need to install a new root certificate on April 15, 2029.

Below are some common issues and solutions for various programming languages:

Common JAVA Errors:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Possible cause: The code sets javax.net.ssl.trustStore. You can search for the keywords trustStore or TrustManager in the code to confirm.

Solution:

Method 1:Delete the code specifying javax.net.ssl.trustStore

Method 2: Install the new root certificate by adding it to the specified trustStore. Operating command: keytool -importcert -keystore cacerts -storepass changeit -noprompt -file ./DigiCertGlobalRootG2.crt -alias digicertglobalrootg2

Common C++ Errors:

cURL error 60: SSL certificate: unable to get local issuer certificate. 
CURLE_SSL_CACERT (60)  peer certificate cannot be authenticated with known CA certificates.

Possible cause: CURLOPT_CAINFO is set in the code. You can search for the keyword CURLOPT_CAINFO in the code to confirm.

Solution:

Method 1: Delete the code related to curl_easy_setopt(pCurl,CURLOPT_CAINFO,"./rootca.pem");

Method 2: Update rootca.pem by replacing it with the latest version from the libcurl official website

Common PHP Errors:

cURL error 60: SSL certificate: unable to get local issuer certificate. CURLE_SSL_CACERT (60)  peer certificate cannot be authenticated with known CA certificates.

Possible cause: CURLOPT_CAINFO is set when using libcurl. You can search for the keyword CURLOPT_CAINFO in the code to confirm.

Solution:

Method 1: Delete code similar to curl_easy_setopt(pCurl,CURLOPT_CAINFO,"./rootca.pem");

Method 2: Update rootca.pem by replacing it with the latest version from the libcurl official website

Common C# Errors:

The callback function set by RemoteCertificateValidationCallback returns false

Possible cause: The operating system does not have the new root CA

Solution: Install the new root certificate

Common Python Errors:

SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:581)

Possible cause: The code specifies a root certificate file using verify. You can search for the keyword “verify” in the code to confirm. Similar codes such as:

response = requests.post(
"https://api.mch.weixin.qq.com/secapi/pay/refund"，
verify="./rootca.pem",
     ……
);

Solution:

Method 1: Delete the verify parameter

Method 2: Update rootca.pem by replacing it with the latest version from the libcurl official website

Common go Errors:

x509: certificate signed by unknown authority .

Possible cause: When initiating https requests, RootCAs is used to specify a root certificate file. You can search for the keyword RootCAs in the code to confirm. Similar codes such as:

roots := x509.NewCertPool()
roots.AppendCertsFromPEM([]byte(rootPEM))
tr := &http.Transport{
    TLSClientConfig: &tls.Config{RootCAs: roots}，
}
client := &http.Client{Transport: tr}

Solution:

Method 1: Delete the configuration itemRootCAs

Method 2: Update rootca.pem by replacing it with the latest version from the libcurl official website

Common Ruby Errors:

SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

Possible cause: When initiating https requests, a root certificate file is specified using ssl_ca_file or cert_store. You can search for the keywords ssl_ca_file or cert_store in the code to confirm. Similar codes such as:

response = RestClient::Resource.new(
    "https://api.mch.weixin.qq.com/secapi/pay/refund"，
    :ssl_client_cert  =>  OpenSSL::X509::Certificate.new(File.read("./apiclient_cert.pem "))，
    :ssl_client_key => OpenSSL::PKey::RSA.new(File.read("./apiclient_key.pem "))， 
    :ssl_ca_file => "./rootca.pem"，
    :verify_ssl=>OpenSSL::SSL::VERIFY_PEER).post(data);

or

sock.cert_store.add_path('/usr/lib/ssl/certs/weixin')
sock.cert_store.add_file('/usr/lib/ssl/certs/weixin/rootca.pem')

Solution:

Method 1: Delete the parameters specified by ssl_ca_file and cert_store

Method 2: Update rootca.pem by replacing it with the latest version from the libcurl official website

Common NodeJs Errors:

Caught exception: Error: CERT_UNTRUSTED

Possible cause: The code specifies a root certificate file using ca. You can search for the keywords ca or rootca in the code to confirm. Similar codes such as:

const options = {
    hostname: api.mch.weixin.qq.com ',
    pfx: await readFile('./apiclient_cert.p12'),
    ca: await readFile('./rootca.pem'),
};
const req = https.request(options, (res) => {
……

Solution:

Method 1: Delete the parameter specified by ca

Method 2: Update rootca.pem by replacing it with the latest version from the libcurl official website

For other languages, please refer to the corresponding TLS/SSL store manuals.

5. FAQs

Q1: What is a server certificate?

A: A server certificate, commonly referred to as an “SSL certificate” or “HTTPS certificate,” is issued by an authoritative CA institution to authenticate a website’s identity, and establish a secure transmission channel between the client and the website using the TLS/SSL protocol. WeChat Pay’s server certificate, issued by the authoritative institution DigiCert, allows partners to authenticate WeChat Pay’s identity when calling WeChat Pay APIs

Q2: What is a root certificate?

A: A root certificate is a certificate issued by an authoritative CA institution to itself, serving as the starting point of the trust chain and the foundation for establishing trust between the certificate authority (CA) and users. Operating systems, browsers, and TLS/SSL development libraries usually come with the software distribution with the root certificate of their trusted authorities.

Q3: Are root certificates and API certificates the same?

A: No, they are not related. The “root certificate” is used to verify the authenticity of WeChat Pay’s domain name and server, usually built in the operating system or execution environment (such as JRE). The “API certificate” is used to verify the merchant’s identity and is typically used when calling WeChat Pay v2 fund-related interfaces (such as refunds, enterprise red packets, enterprise payments, etc.) or v3 interfaces.

Q4: Why does WeChat Pay need to replace server certificates?

A: Root certificates have expiration dates, and once they expire, they cannot be used to verify server certificates. Therefore, WeChat Pay has requested for a new server certificate from an authority (CA), to avoid problems when merchants call the WeChat Pay API after the old root certificate expires.

Q5: What actions do merchants need to take to verify and correct server certificates?

A: Merchants’ technical development team should:

1. Verify if their system is compatible with the new server certificate for WeChat Pay.
2. If yes, no action is required. If no, refer to the correction guidelines to identify and correct the issue.

Note:

• There is no cost for merchants to verify or install new root certificates as per the guidelines;
• The API certificates on the merchant platform do not need to be replaced;
• Other https certificates being used by merchants do not need to be replaced or upgraded.

Q6: How can merchants verify if G2 root certificates are already installed on their servers?

A: Using Linux systems as an example: The location of the Linux system’s trusted root certificate store may vary depending on the distribution version: Debian/Ubuntu: /etc/ssl/certs/ca-certificates.crt CentOS/RHEL/Fedora/TencentOS: /etc/pki/tls/certs/ca-bundle.crt Merchants can use the following command to verify if the system already includes G2 root certificates:

grep "DigiCert Global Root"  /etc/pki/tls/certs/ca-bundle.crt
# DigiCert Global Root CA
# DigiCert Global Root G2

Note: The example shows that the system already includes both G1 and G2 root certificates

Q7: Can merchants install the new root CA certificate in advance before WeChat Pay changes the certificate?

A: It is necessary to install it in advance, and it is recommended to install it before 0:00 on September 20, 2024. Starting from 0:00 on September 20, 2024, WeChat Pay will gray release new server certificate in the production environment to verify whether the merchant’s system is compatible with the new certificates. During the process of replacing the new certificate, WeChat Pay will use both the old and new server certificates at the same time, and partners should be able to handle this situation normally. Therefore, partners’ servers need to include both new and old root certificates.

Q8: When should partners complete the verification and correction? What are the impacts of not verifying?

A: Partners should complete the verification and correction before 0:00 on September 20, 2024. If the merchant’s system implementation is already compatible with the new server certificate, it will not affect the business. If the partner’s system implementation is not compatible with the new server certificate, it will result in the inability to interact properly with WeChat Pay’s system, affecting the business.

Q9: If a partner cannot complete the compatibility correction on time and encounters exceptions when WeChat Pay gray releases the new certificate, how should they handle it?

A: If the partner’s system is verified to be incompatible with the new certificate, the merchant should complete the correction before 0:00 on September 20, 2024. If the correction cannot be completed on time, we can provide a temporary environment that still uses the old certificate. Partners can use it by binding an IP to the host to temporarily avoid the impact of certificate replacement. It is crucial to complete the system corrections before 0:00 on November 30, 2024, and remove the binding of the temporary environment IP to resume normal linking up with WeChat Pay’s production environment. The corresponding relation between the temporary environment host and IP is as follows:

6. Special Reminder

1. To detect in advance “Whether partners will be affected by certificate replacement?” and “Whether they have upgraded their root certificates?” , WeChat Pay will start from 0:00 on September 20, 2024, forwarding some partner requests to servers that have deployed new certificates and gradually increasing the gray release ratio. When partners do not support the new server certificate, SSL-related errors may occur. Usually, retry can resolve the issue;
2. The root certificate upgrade is only related to servers and applications, has nothing to do with merchant IDs. As long as all merchant Ids on the same server are upgraded, they can function normally;
3. If you are initiating requests to WeChat Pay through a proxy server, you will need to modify the proxy server’s configuration.

7. Contact Us

If partners encounter difficulties during the verification or correction process, they can consult WeChat Pay Technical Support in the WeChat group or email to wxp_globalts@tencent.com. We will have dedicated person to provide solutions and replies.

8. Appendix

DigiCert Original Announcement: DIGICERT ROOT AND INTERMEDIATE CA CERTIFICATE UPDATES 2023