WeChat Pay

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 lose trust 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. Partners' technical teams should carefully read this guideline and complete the relevant verification and correction to avoid affecting normal transactions.

Note:

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 an email to wxp_globalts@tencent.com, and we will have a dedicated person to provide solutions and replies.

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 "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:

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

You can correct this using one of the following two solutions:

It is recommended to use "Solution 1" for correction as it provides better compatibility. The reason is that 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:

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 returnsfalse 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 item RootCAs

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 Node.js 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 trust store manuals.

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 partner'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 partners call the WeChat Pay API after the old root certificate expires.

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

A: Partner' technical development team should:

Q6: How can partners 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 Partners 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 partners 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 the new server certificate in the production environment to verify whether the partner's system are compatible with the new certificates. During the process of replacing the new certificate, WeChat Pay will use both the old and new server certificates simultaneously, 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 partner'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 partner 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:

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, and has nothing to do with partner IDs. As long as all partner 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.

微信支付使用HTTPS来保证通信安全，商户与微信支付服务器通信前，要在客户端的操作系统或者执行环境(如JRE等)中部署权威机构的根证书。 商户调用微信支付API的过程中，会用根证书来校验微信支付服务器及域名的真实性。 受Mozilla信任库的根证书最新信任策略（全球所有 CA 的可信根证书生成后最少 15 年更换一次，超过时间的可信根会逐渐被 Mozilla 停止信任）影响，DigiCert 将逐步停用旧根体系（G1）颁发 TLS/SSL 证书，并开始使用新根体系（G2）颁发 TLS/SSL 证书。

当前微信支付服务器证书的颁发根CA是Digicert Global Root CA (G1)，微信支付计划于2024年9月20日0:00开始，逐步启用采用DigiCert Global Root G2根CA颁发的新服务器证书，商户的技术开发人员应仔细阅读本指引，并完成相关验证和修正，以免影响正常交易。

注意:

商户需确认与微信支付对接的系统或终端设备可兼容新的服务器证书，并参考“验证指引”章节的方法，在2024年9月20日0:00日之前完成验证:

• 如果验证结果正常，商户不需要做其他任何事情
• 如果验证结果异常，商户需要修改相关的系统实现或配置，且需最晚于2024年9月20日0:00之前完成修正，否则商户的业务系统与微信支付系统之间将不能正常进行HTTPS通讯，将影响业务正常运行.

商户在验证和修正过程中遇到问题，可在联系技术支持咨询，我们会有专人进行解答回复.

验证方式：绑定host，请求已部署新证书的微信支付服务器

商户可通过修改操作系统的hosts文件来绑定IP，例如，可在hosts文件中新增一行如下内容，实现将域名 "apihk.mch.weixin.qq.com" 绑定到新证书环境：

43.142.224.50 apihk.mch.weixin.qq.com

在linux系统下，hosts文件的完整路径为"/etc/hosts"，在Windows系统下，hosts文件的完整路径为"C:\Windows\System32\drivers\etc\hosts"

商户应根据当前实际对接使用的域名来修改hosts文件配置，已部署新服务器证书的验证环境host和IP对应关系如下

注意：

大部分情况下，验证失败是以下两种情况导致的:

可通过以下两个方案修正:

推荐使用“方案一”来修正，该方案的兼容性更好。原因是：新的G2根证书将于 2029年4月15日不再被Mozilla信任，到时候同样要更换新的根证书。使用方案一修复的话，你的系统中很可能已内置了后续需更换使用的根证书，从而不受影响。如果使用方案二进行修复的话，在 2029年4月15日仍可能需安装新的根证书。

下面介绍各种开发语言可能碰到的问题及解决方法：

Java常见错误：

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

可能原因：代码中设置了 javax.net.ssl.trustStore. 可以在代码中搜索关键字trustStore或者TrustManager来确认。

解决方法:

C++常见错误

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

可能原因：代码中设置了CURLOPT_CAINFO， 可以在代码中搜索关键字CURLOPT_CAINFO来确认.

解决方法:

方法一：删除掉curl_easy_setopt(pCurl, CURLOPT_CAINFO, "./rootca.pem");相关的代码

方法二：更新rootca.pem，用 libcurl 官网最新的替换即可

PHP常见错误：

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

可能原因：使用libcurl时设置了CURLOPT_CAINFO，可以在代码中搜索关键字CURLOPT_CAINFO来确认

解决方法:

方法一：删除掉类似curl_easy_setopt(pCurl, CURLOPT_CAINFO, "./rootca.pem");的代码

方法二：更新rootca.pem，用 libcurl 官网最新的替换即可

CC#常见错误：

RemoteCertificateValidationCallback设置的回调函数返回false

可能原因：操作系统中没有新的根CA

解决方法：安装新的根证书

Python常见错误：

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

可能原因：代码中用verify指定了根证书文件，可以在代码中搜索关键字“verify”来确认。类似的代码如

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

解决方法:

方法一：删除verify参数

方法二：更新rootca.pem libcurl 官网最新的替换即可

go常见错误：

x509: certificate signed by unknown authority .

可能原因：发起https时， 用RootCAs指定了根证书文件，可以在代码中搜索关键字RootCAs

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

解决方法:

方法一：删除配置项RootCAs

方法二：更新rootca.pem，用libcurl 官网最新的替换即可

Ruby常见错误:

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

可能原因：发起https时， 用 ssl_ca_file 或者 cert_store. 指定了根证书文件，可以在代码中搜索关键字 ssl_ca_file 或者 cert_store 来确认。类似的代码如:

 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);

或者

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

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

解决方法:

方法一：删除 ssl_ca_file 及 cert_store指定的参数

方法二：更新rootca.pem，用 libcurl 官网最新的替换即可

Node.js常见错误:

Caught exception: Error: CERT_UNTRUSTED

可能原因：代码中用ca指定了根证书文件。 可以在代码中搜索关键字ca或者rootca来确认。类似的代码如：

  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) => {
  ……

解决方法:

方法一：删除ca指定的参数

方法二：更新rootca.pem, libcurl 官网最新的替换即可

其它语言请参考对应的TLS/SSL库相关手册。

Q1：什么是服务器证书？

A：服务器证书通常又叫“SSL证书”、“HTTPS证书”，它由权威CA机构颁发，用于对网站进行身份鉴定，并使客户端与网站之间通过TLS/SSL协议建立起安全传输通道。微信支付的服务器证书是由权威机构DigiCert颁发，商户调用微信支付API时，能通过该证书来认证微信支付的身份。

Q2：什么是根证书？

A：根证书是权威CA机构给自己颁发的证书，是信任链的起始点，是证书颁发机构（CA）与用户建立信任关系的基础。操作系统、浏览器、TLS/SSL开发库通常随软件发行包预置其信任的权威机构的根证书。

Q3: 根证书和API证书是同一个吗？

A：不是，两者没有关系。“根证书”是用来校验微信支付的域名及服务器的真实性， 通常内置在操作系统或者执行环境（如JRE等）中;“API证书”是用来证实商户身份的，通常在调用微信支付v2的出资金类接口（如：退款、企业红包、企业付款等）或v3接口时，才会使用到API证书。

Q4: 微信支付为什么要更换服务器证书？/strong>

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