Product Documentation General instructions Access Guidelines FAQs

API Rules

Update Time：2025.03.24

Protocol Rules

The following specifies the rules for calling the API when a merchant accesses WeChat payment:

Transfer Mode	Use HTTPS for secure transactions
Submit Mode	Use POST method
Data Format	Data submitted and returned is in XML format
Char Encoding	Use UTF-8 character encoding
Signature Algorithm	MD5 or HMAC-SHA256
Signature Requirement	Signature-checking is required for requesting and receiving data. For more information, see Signature Algorithm.
Certificate Requirement	A merchant certificate is required for calling the Submit Refund API or Revoke Order API.
Logic Judgment	Determine protocol field, service field and transaction status.

Security Specifications

Signature Algorithm

General steps to create a signature:

Step 1: Presume all data sent and received is the set M. Sort non-empty values in M in ascending alphabetical order (i.e. lexicographical sequence), and join them into string A via the corresponding URL key-value format (e.g. key1=value1& key2=value2…).

Notes:

a. Sort parameter names in ascending alphabetical order based on their ASCII encoded names (e.g. lexicographical sequence);

b. Empty parameter values are excluded in the signature;

c. Parameter names are case-sensitive;

d. When checking returned data or a WeChat push notification signature, the transferred sign parameter is excluded in this signature as it is compared with the created signature.

Step 2:Add "key= (API key value) to the end of stringA to get stringSignTemp, perform MD5 arithmetic on stringSignTemp, convert all result chars to upper case, thus get sign's value (signValue).

Example:

For the following transferred parameters:

appid：wxd930ea5d5a258f4f

mch_id：10000100

device_info： 1000

body：test

nonce_str：ibuaiVcKdpRxkhJA

a. Sort ASCII code of parameter names by lexicographical sequence based on the format of "key=value"

stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA";

b. Join API keys

stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"

sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"

Obtain data to be transferred below:

1<xml>
2<appid>wxd930ea5d5a258f4f</appid>
3<mch_id>10000100</mch_id>
4<device_info>1000<device_info>
5<body>test</body>
6<nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
7<sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign>
8<xml>

WeChat provides online signature tools for this API: URL1.

Random String Algorithm

nonce_str is included in WeChat payment API protocols to ensure unpredictability for signatures. We suggest calling the random() function to create a signature and convert its value into a string.

Merchant Certificate

1. Obtain Merchant Certificate

APIs related to payment rollbacks (such as refunds or revoked orders) require a merchant's certificate. The certificate is issued to merchants via an email notification after the merchant applies for WeChat payment successfully. There are four certificates that might be required as indicated below:

Table 5.2: Certificate Description

Certificate Attachment	Description	Use Case	Remarks
pkcs12 format (apiclient_cert.p12)	Includes certificate for private key information, in p12(pfx) format and issued by WeChat payment for identity verification	Calling the Revoke Order API and Submit Refund API	Double-click to import into a Windows system and enter certificate password as prompted. By default, the certificate password is the merchant's ID (e.g. 10010000)
pem format for certificate (apiclient_cert.pem)	apiclient_cert.pem certificate files may be imported to create a certificate in pem format. Do not disclose to others.	pem format should be used for PHP applications as PHP can't use the p12 format	You can also use the "openssl" command to import the p12-format certificate as below: openssl pkcs12 -clcerts -nokeys -in apiclient_cert.pem -out apiclient_cert.pem
pem format for certificate secret key (apiclient_key.pem)	apiclient_cert.pem certificate files may be imported to create a certificate in pem format.	pem format should be used for PHP applications as PHP can't use the p12 format	You can also use the "openssl" command to import the p12-format certificate as below: openssl pkcs12 -nocerts -in apiclient_cert.pem -out apiclient_key.pem
CA certificate (rootca.pem)	WeChat payment API server also deploys server certificates to verify identity for WeChat payment. When merchants call APIs, the authenticity of the server called and domain name shall be verified.	This file is the root certificate issued by authorities that sign WeChat payment certificates, which can be used to verify the authenticity of WeChat payment server certificates.	Root certificates are built-n to some tools. For tools without root certificates, the ones provided here may be used.

2. Use Merchant Certificate

a. apiclient_cert.p12 is merchant's certificate files for all R&D operations except PHP-based development.

b. Merchants using a .NET environment should ensure that their framework version is greater than 2.0. They can double-click to install the certificate "apiclient_cert.p12" before using.

c. The default password for the calling merchant's certificate and installation is merchant's ID (mch_id).

d. "apiclient_cert.pem" and "apiclient_key.pem" are required for PHP-based development, and rootca.pem is CA certificate.

For more invocation examples, see Demo outbound links provided by WeChat payment：

cert.7z

3. Merchant Certificate Security

Certificate files should not be stored in a virtual directory on the web server. Instead, they should be placed in a directory with strict access control in order avoid the certificate being downloaded by others. The Merchant's server should also be free from viruses and trojan horses to avoid potential certificate theft.

Merchant's Callback API Security

In many network environments, HTTP requests bear the risk of DNS spoofing, unwanted pop-ups, and data theft and modifications. The Merchant's callback API should use HTTPS to ensure data transfer security. For this reason, we suggest all merchants use HTTPS for all WeChat payment callbacks. For more information, see the HTTPS Building Guide.

Business Category

Merchant Category Codes	Merchant Category	Merchant Category Codes	Merchant Category
343	Shoes&Garments	492	Stationery/office supplies
484	Comprehensive mall	493	Air Ticket
485	Food	494	Other trade industry
486	Cosmetics	528	Overseas Education
487	Maternal and infant	529	Travel ticket
488	Digital appliance	530	Car rental
489	Logistics	531	international Conference
490	Education Industry	532	Software
491	Hotel Industry	533	Medical Service

Merchant's Callback API Security

In many network environments, HTTP requests bear the risk of DNS spoofing, unwanted pop-ups, and data theft and modifications. The Merchant's callback API should use HTTPS to ensure data transfer security. For this reason, we suggest all merchants use HTTPS for all WeChat payment callbacks. For more information, see the HTTPS Building Guide.

Getting OpenID

WeChat Official Account Admin Platform:

After messaging between a follower and Official Accounts, the Official Accounts can get the follower's OpenID. Each user has a unique OpenID after its WeChat ID is encrypted. User's OpenID varies from different Official Accounts.

Official Accounts can get user's OpenID by the API below.

For information about user's alias, photo picture, gender, location, language, and following time, user's authorization is required.

URL: http://mp.weixin.qq.com/?lang=en_US

To use OpenIDs from different platforms as one ID for the same user, developers can use the API below:
URL: https://developers.weixin.qq.com/miniprogram/en/dev/

WeChat Open Platform:

Mobile apps can use the API below to get user's OpenID

Website apps can use the API below to get user's OpenID