WeChat Pay

1. API Call Rules

WeChat Pay REST API is an http API designed in a RESTful style. All API requests must be made in HTTPS. The message body of the request and response must be in the JSON format.

1.1 Authentication

The WeChat Pay REST API verifies the identity of the merchant and the integrity of the data by verifying the signature of the request. The merchant needs to use its private key to sign the combination of key data such as API URL and message body with SHA-256 with RSA. The signature information of the request is transmitted through the http header authorization. For details, please refer to Sign Signature Generation Method. Requests that do not carry a signature or with failed signature verifications will not be executed. In that case, the error “401 Unauthorized” will be returned.
The process result response of the API will also include signature information. We highly recommend that the merchant use the public key contained in the WeChat Pay platform certificate to verify the signature of the response.

1.2 Certificate

WeChat Pay REST API currently only supports certificates issued by a certificate authority (CA). Merchants need to download the certificate tool to generate the certificate request string, and submit the certificate request string to the merchant platform to obtain the merchant API certificate. The private key can only be exported through the certificate tool. The merchant private key must be kept properly. Do not expose the private key in public, such as uploading to Github or writing in client code.

1.     ● New merchants please refer to What is the API certificate? How to get the API certificate?
2.     ● Please refer to Guide for Upgrading WeChat Pay API Certificate (Technical Personnel) if you have been connected and have used the certificate issued by WeChat Pay.

Call the platform certification API to obtain the certificate from the WeChat Pay platform.

In some cases, like when the private key is divulged, the certificate needs to be updated. In order to ensure that the use of the API is not affected during the certificate replacement process, the request and response must contain the certificate serial number to declare the certificate used for signing or encryption.

1.     ● Use the private key to sign the merchant signature. The certificate serial number is contained in the serial_no of authorization in the http header of the request.
2.     ● Use the WeChat Pay private key to sign the WeChat Pay signature. The certificate serial number is contained in the Wechatpay-Serial in the http header of the request.
3.     ● Use the WeChat Pay platform public key for encryption when sending sensitive information. The certificate serial number is contained in Wechatpay-Serial in the http header of the request.

1.3 Data Format

The WeChat Pay REST API uses only the data exchange format with the message body of JSON. The Content-Type and Accept corresponding to the http header must be set as application/json, except for the image upload API.

1.4 Character Set

The WeChat Pay REST API only supports a subset of the UTF-8 character encoding: characters encoded with one to three bytes. Characters encoded with four to six bytes in the Unicode auxiliary plane are not supported.

1.5 Parameter Rules

1.     ● Whether the request succeeds is irrelevant with the order of the request parameters.
2.     ● Whether the request succeeds is irrelevant with the order of the key-value pairs in the request JSON.
3.     ● When the response is processing, the order of the key-value pairs in the response JSON should not be assumed.
4.     ● New parameters or JSON key-value pairs may be added to the new API version.
5.     ● The new API version will not remove existing parameters or key-value pairs of JSON.
6.     ● When the value of a JSON key-value pair in the request or response is null, it can be omitted.

The data in the API response may include data entered by the merchant, which may be user input that has yet been checked. In order to avoid XSS (cross-site scripting) attacks, the caller should conduct appropriate escaping or filtering based on the scenario before using the response data.

1.6 Error Message

The WeChat Pay REST API indicates the results of request processing using http status codes.

1.     ● If a request is processed successfully, the message body of 200 will be returned in case of a response, and 204 will be returned in case of no response.
2.     ● If the request is received and waiting for processing, 202 will be returned.
3.     ● If the request processing fails because the input parameters necessary are missing or there's insufficient balance during payment, an error code within the range of 4xx will be returned.
4.     ● If a service system error occurs in WeChat Pay while the request is processing, a status code of 500/501/503 will be returned. This situation rarely happens.

HTTP status codes

Error codes and error prompts

When the request processing fails, in addition to the http status code that indicates the error, the API will return an error in the message body to explain the specific error reason.

1.     ● code: detailed error code
2.     ● message: error description, explain the cause of the error in simple language
3.     ● field: indicates the location of the error parameter When the error parameter is in the JSON of the request body, fill in JSON Pointer that points to the parameter. When the error parameter is in the URL of the request or querystring, fill in the variable name of the parameter.
4.     ● value: wrong value
5.     ● issue: specific cause of error

Example: 
 { "code": "PARAM_ERROR", "message": "parameter error", "detail": { "field": "/amount/currency", "value": "XYZ", "issue": "Currency code is invalid", "location" :"body" } }

1.7 Date Format

All date objects adopt the format defined by ISO 8601. Example:

YYYY-MM-DDTHH:mm:ss.SSSZ
YYYY-MM-DDTHH:mm:ssZ
YYYY-MM-DDTHH:mm:ss.SSS+08:00
YYYY-MM-DDTHH:mm:ss+08:00

1.8 User Agent

The http protocol requires the requesting client to use the http header User-Agent to identify itself in each request. WeChat Pay recommends one of the following two methods for calling:

1.Use the default User-Agent of the http client; or

2.Follow the http protocol and formulate its own unique User-Agent using the name and version of its own system and app.

WeChat Pay REST API may refuse to process requests without User-Agent.

1.9 Response Language

The WeChat Pay REST API allows the caller to declare the natural language of the error description in the response. If necessary, set the Accept-Language http header of the request. The following languages are supported currently:

1.10 Unique Request Identifier

WeChat Pay assigns a unique identifier to each request received. The unique request identifier is included in the http header Request-Id of the response. For help via WeChat Pay, please provide the unique identifier of the request so that we can locate the specific request more quickly.

2. Signature Generation Method

WeChat Pay will authenticate data to ensure that the information carried is true, valid and reasonable. SHA256 with RSA is used to sign. The following describes the signing method and steps of request and response data.

Public and private key generation tool:

The tool for generating third-party CA certificates and keys can be downloaded from

The following shows how a request signature is generated. The following is the original http request message:

YYYY-MM-DDTHH:mm:ss.SSSZ
Request link: https://api.mch.weixin.qq.com/hk/v3/transactions/micropay
POST data: 
{
"appid": "wx2421b1c4370ec43b",
"transaction_id": "1008450740201411110005820873",
"out_trade_no": "1415757673"
}

2.1 Request Data Signature

Constructing the string to be signed

Before using a specific signature algorithm, the merchant needs to construct a string to be signed.

Step 1: Obtain the http request method (such as GET, POST, and PUT)

POST

Step 2: Get the requested URL, and remove the domain part. If the link contains parameters, the parameter value must be URLencoded. The URL used in the example is

/hk/v3/transactions/micropay

Step 3: Obtain the current time stamp of the system when the request is initiated, that is, the total number of seconds from January 1, 1970, 00: 00: 00, GMT (January 1, 1970, 08: 00: 00, Beijing time). The time stamp must be the most current. If the time stamp is 300 seconds later than the time of the WeChat Pay server, the WeChat Pay server will reject the request and report an error. Merchants should keep their system time accurate.

1507709906

Step 4: Generate a request random string. The algorithm can be customized by the developer (you can call the system random number generation function to convert it into a string). The recommended length is no less than 10 digits.

kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg

Step 5: Get the submitted data.

{
"appid": "wx2421b1c4370ec43b",
"transaction_id": "1008450740201411110005820873",
"out_trade_no": "1415757673"
}

Step 6: Formulate the string to be signed according to the following method. The string to be signed has five lines. Each line includes a parameter and ends with \n, including the last line. If a line is empty, a newline character is also required. \n is the newline character (ASCII code value is 0x0A).

HTTP request method\n
URL\n
Request time stamp\n
Request random string\n
Request message\n

According to the rules above, the string to be signed in the request message will be:

POST
/hk/v3/transactions/micropay
1507709906
kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg
{
"appid": "wx2421b1c4370ec43b",
"transaction_id": "1008450740201411110005820873",
"out_trade_no": "1415757673"
}

Calculating signature value

The signature functions of many programming languages support signing the data to be signed. We recommend that merchants call such functions and use private key to perform SHA256 with RSA signature on the string to be signed, and perform Base64 encoding on the signing result to obtain the signature value. If the programming language or library used by the merchant only supports signing abstract data, please follow the steps below to calculate the signature value:

Step 1: Use SHA256 to calculate the abstract of the string to be signed to obtain the abstract information.

Step 2: Use the merchant's private key to perform RSA signature on the abstract information (SHA256 signature type) to obtain the binary signature value. Please refer to RSA_sign() of OpenSSL

Step 3: Use Base64 to encode the signature value to get the final signature value.

Setting the http header

WeChat Pay requires the request to send the signature through the http Authorization header. Authorization is composed by the authentication type and signature information.

Authorization: Authentication type and signature information

The specific composition is:

Authentication type: WECHATPAY2-SHA256-RSA2048 currently

Signature information:

Merchant ID mchid (the merchant ID is the request initiator ID, and WeChat Pay will authenticate the initiator)

Request random string nonce_str (must be consistent with the value of the signature field) Signature value signature

Times tamp (must be consistent with the value of the signature field) Certificate serial number serial_no

The following is an example of the Authorization header: (the example may have line breaks due to typesetting. The actual data should be in one line, and there is a space before mch_id)

Authorization: WECHATPAY2-SHA256-RSA2048 mchid="10000100",nonce_str="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg",signature="hDV4aXhMvfZ31NABElvWHWuxYiR7lB1sjzcpldpWul/62o75d90l5oznquE+uVORPESfzBpCdtU6IiL+1Cdy3rG01sKXrWfFnjr4jm/imFxbq8BbVpE+HbrRXkR/jrc6gqSVuIjJfXSMK1yL5G35WgUWzWdAKiV3ELQk/sSYrhnOiulve/xM2bJvYFQDl/dvMazxW930JLm0lv1tEMuHuqcx5WN+1fq3VJ+J9UvwVTjQT8eXmHAzaYxXHEoDyN2T5/AVzZTuzcCt1cFk5Sj/tNUvDMklxy+eOF7hOUCFzo98Z42OsdpC3GV02mYOApeNwVB7I5fCB//jerFqf9/VjA==",timestamp="1507709632",serial_no=”345D5C1DB746787546E06E6DAD9E5BE987CEDFCF”

An http request with signature is obtained at last.

POST /hk/v3/transactions/micropay HTTP/1.1
Date: Fri, 07 Jul 2017 08:19:58 GMT
Accept: application/json
Connection: close
User-Agent: curl/7.54.0
Content-Type: application/json
Authorization: WECHATPAY2-SHA256-RSA2048 mchid="10000100",nonce_str="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg",signature="hDV4aXhMvfZ31NABElvWHWuxYiR7lB1sjzcpldpWul/62o75d90l5oznquE+uVORPESfzBpCdtU6IiL+1Cdy3rG01sKXrWfFnjr4jm/imFxbq8BbVpE+HbrRXkR/jrc6gqSVuIjJfXSMK1yL5G35WgUWzWdAKiV3ELQk/sSYrhnOiulve/xM2bJvYFQDl/dvMazxW930JLm0lv1tEMuHuqcx5WN+1fq3VJ+J9UvwVTjQT8eXmHAzaYxXHEoDyN2T5/AVzZTuzcCt1cFk5Sj/tNUvDMklxy+eOF7hOUCFzo98Z42OsdpC3GV02mYOApeNwVB7I5fCB//jerFqf9/VjA==",timestamp="1507709632",serial_no=”345D5C1DB746787546E06E6DAD9E5BE987CEDFCF”
Content-Length: 119

{
"appid": "wx2421b1c4370ec43b",
"transaction_id": "1008450740201411110005820873",
"out_trade_no": "1415757673"
}

2.2 Response Verification Signature

We highly recommend that merchants verify the signature of the response, which can be processed following the steps below. The http message of the response example is:

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 07 Jul 2017 08:19:59 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 97
Cache-Control: max-age=0, private, must-revalidate
Wechatpay-Signature: WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=
Wechatpay-Serial: 2F3B6CA4AED8D40827FAFF9F802136606FE1593C
Wechatpay-Nonce: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Wechatpay-TimeStamp: 1507709906

{
"out_trade_no": "20150806125346",
"prepay_id": "wx201411101639507cbf6ffd8b0779950874"
}

Constructing signature string

First, obtain the response body, the response random string in the http header Wechatpay-Nonce, and the response time stamp in Wechatpay-Timestamp from the response.

Construct the response signature string according to the following rules. \ n is the newline character (ASCII code value is 0x0A).

Reply time stamp\n
Response random string\n
Response body\n

Then, the signature string is:

1507709906
5K8264ILTKCH16CQ2502SI8ZNMTM67VS
{
"out_trade_no": "20150806125346",
"prepay_id": "wx201411101639507cbf6ffd8b0779950874"
}

Obtaining response signature

The response signature of WeChat Pay is entered through the http header Wechatpay-Signature. (The example may have line breaks due to typesetting. The actual data should be in one line.)

Wechatpay-Signature: WcO + t3D8Kg71dTlKwN7r9PzUOXeaBJwp8 / FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28 / Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr / NUc9VeY =

use Base64 to decode the Wechatpay-Signature field value to obtain the signature response.

Verifying signature

The signature verification functions of many programming languages support signature verification of the signature data. We recommend that merchants call such functions and use the public key of the WeChat Pay platform to perform SHA256 with RSA signature verification on the signature string.

If the programming language or library used by the merchant only supports abstract data verification, please follow the steps below to verify the signature:

Step 1: Use SHA256 to calculate the abstract of the signature string to obtain the abstract information.

Step 2: Use the public key of the WeChat Pay platform to perform RSA signature on the abstract information (SHA256 signature type). Please refer to RSA_verify() of OpenSSL.

Note: The serial number of the WeChat Pay certificate is located in the http header Wechatpay-Serial. Check whether the serial number is consistent with the serial number of the WeChat Pay certificate held by the merchant before verifying the signature. For certificate renewal instructions, please refer to Instructions on Obtaining WeChat Pay Platform Certificate.

2.3 Code Example

The API call instance takes development as an example to illustrate the specific data submission and return formats:

Query request:

GET https://api.mch.weixin.qq.com/hk/v3/transactions/merchant-trade-no/{merchant_trade_no}

Setting the http header

{
    "id": "1008450740201411110005820873",
    "sp_appid": "wx2421b1c4370ec43b",
    "sub_mchid": "10000100",
    "sp_mchid": "20000100",
    "out_trade_no": "20150806125346",
    "payer": {
      "sp_openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
    },
    "amount" : {
        "total": 528800,
        "currency": "HKD",
        "payer_total": 518799,
        "payer_currency": "CNY",
        "exchange_rate" : {
            "type": "SETTLEMENT_RATE",
            "rate": 8000000
        }
    }, 
    "trade_type": "JSAPI",
    "trade_state": "SUCCESS",
    "trade_state_desc": "payment succeeded",
    "bank_type": "CCB_DEBIT",
    "attach": "payment test",
    "success_time": "2018-06-08T10:34:56+08:00",
    "promotion_detail":[
        {
            "promotion_id":"109519",
            "name":"single product discount-6",
            "scope":"SINGLE",
            "type":"DISCOUNT",
            "amount":1,
            "currency":"HKD",
            "activity_id":"931386",
            "wechatpay_contribute_amount":1,
            "merchant_contribute_amount":0,
            "other_contribute_amount":0,
            "goods_detail":[
                {
                    "goods_id":"iphone6s_16G",
                    "goods_remark":"goods remark",
                    "quantity":1,
                    "price":528800
                }
            ]
        }
    ]
}

{
｛
     “code” : ”INVALID_REQUEST”,
     “message” : “INVALID_REQUEST”
    ｝

3. Return Status and Judgment

Step 1: Check the http status code. Refer to the http error codes in 3.1.6 Error Message.

Step 2: Verify the return signature of the 2** status codes; no signature will be returned for 5** status codes, and signature return for 4** status codes will be supported in the future.

Step 3: Check the payment status. The specific status of the order cannot be returned in the error code. The order status is subject to the payment result, order check API, and payment notification.

Step 4: Payment, order check, payment notification APIs also need to verify the order amount.

4. API Domain

https://apihk.mch.weixin.qq.com/hk/v3/transactions/jsapi (recommended access point: overseas)

https://api.mch.weixin.qq.com/hk/v3/transactions/jsapi (recommended access point: domestic)

Note: Merchants can choose the optimal domain for access based on actual needs. Merchants should ensure compatible access domains so that they can automatically switch to other domains when one fails.

5. API Domain Name

https://apihk.mch.weixin.qq.com/hk/v3/transactions/app (Recommended for merchants outside China)

https://api.mch.weixin.qq.com/hk/v3/transactions/app (Recommended for merchants within China)

Note: A merchant can select a domain name which is most suitable for the merchant's request. Compatibility should be ensured. If an exception occurs when a domain name is accessed, another domain name can be used automatically.

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