1. Background Description
To give merchants a simple, consistent and easy-to-use development experience, WeChat Pay has launched API V3 for institutions/merchants around the world. For the specific rules of this version of API, see "APIv3 Interface Rules”.
For the onboarded institutions/merchants that have been connected to API v2, please complete the API upgrade by referring to the following upgrade instructions and precautions.
For connected institutions/merchants outside of Hong Kong, the default API version used is API v2. Subsequent API upgrades can be decided by individual institutions/merchants as needed. If API v2 is still used, the relevant documents can be viewed through the API v2 document center. In case of upgrade, complete the API upgrade by referring to the following upgrade instructions and precautions.
Tips API upgrade is not mandatory. Institutions can choose whether to perform upgrade as needed, and can continue to use the original API v2.
Note:
Institutions and merchants in Hong Kong who have connected to API v3 HK can refer to the relevant documents of API v3 Global for subsequent product access. The original API v3 HK can be still used, but the corresponding documents will be gradually withdrawn.
Tips API v3 HK and API v3 Global differs only in the request address of each API and are consistent in all other aspects. For more information, please refer to API v3 Global document center.
2. Parameter Description
Compared with the API v2 interface of XML+MD5 used currently, the product access process and product business process of the new API v3 Global have not changed. The main differences lie in the API agreement. The specific differences are listed below:
| API v3 Global | API v2 | |
|---|---|---|
| Request mode | GET/POST | POST |
| Data Format | JSON | XML |
| Signature method | RSA | MD5/HMAC-SHA256 |
| API KEY | Used to encrypt sensitive information | Used for signature verification |
| Certificate | Used for signature verification | Used for mutual authentication |
3. Parameter Description
appid：If the onboarded institutions/merchants that have been connected to API v2 need to be upgraded to API V3, they can continue to use the existing official account appid without additional replacement or upgrade.
mch_id：Consistent with the situation of appid, the existing mch_id can still be used without re-submitting an application or performing an upgrade.
sub_mch_id：Similarly, sub_mch_id can be used without re-submitting an application or performing an upgrade.
sub_appid：The sub-merchant's appid can also be used without re-submitting an application or performing an upgrade.
API key：This parameter will not be used in API V3, and the set API key can be retained when the merchant upgrades the API.
API key v3： As a development parameter added for API V3, it is used for the encryption and decryption of sensitive information. For specific purpose and usage, refer to "Encryption/Decryption"; for setting method, refer to the pre-access preparation of each product.
Certificate: The certificate issued by CA needs to be used to call API V3. Log in to the merchant platform first, go to account settings > API security directory, and check the API certificate option. If the interface is shown in the figure below, the certificate corresponding to the merchant ID has been upgraded to the CA certificate, and API V3 can be directly connected.
If the interface is as shown in the figure below, the certificate used by the current merchant ID is a self-signed certificate. To call API V3, you must first upgrade the certificate.
Click Upgrade on the interface, and then perform upgrade by referring to the pre-access preparation of each product.
Note: The upgraded certificate does not affect use of the current API v2. The upgraded CA certificate can also be used to call the API v2 interface.
After the certificate is upgraded, the new and old certificates are provided with a common validity period of 14 days. The old certificate will expire in 14 days, so the new certificate needs to be deployed to the system in a timely manner.
4. Permission Application
API V3 does not require additional permission application. The connection development of API V3 can start only after the API V3 key is set and the certificate is upgraded.
5. Other Precautions
The new capabilities of WeChat Pay will use API V3 protocol in the future. Institutions/merchants are advised to prioritize using API V3 for business connection.
Page Navigation
