Basic Rules

1. Basic Information

All API requests must be HTTPS ones.

Notice

To prevent malicious hijacking, the verification error of the server certificate should not be ignored during a request.

2. Data Format

All API requests must be HTTPS ones, and the message body of a request and response should be in the JSON format.

Notice

For every API except the API "Upload Images", the Content-Type and Accept in the HTTP header of the API request should be set to

Content-Type: application/json
Accept: application/json

except for the image upload API.

Notice

The data in an API response may contain the merchant-input data that has not been checked. In order to avoid XSS (Cross-site scripting) attack, the caller is recommended to escape or filter the response data as needed by the scenario before using the data.

3. Parameter Rules

• Whether a request is successful is independent of the order of request parameters.

• Whether a request is successful is independent of the order in which the key-value pairs appear in the JSON for request.

• When a response is processed, the order in which the key-value pairs appear in the JSON for response should not be assumed.

• For the new version of APIs, new parameters or JSON key-value pairs may be added.

• For the new version of APIs, existing parameters or JSON key-value pairs will not be removed.

• If the value of a JSON key-value pair in the request or response is null, it can be omitted.

4. Character Set

WeChat Pay API V3 only supports a subset of UTF-8 characters, with each character encoded with 1-3 bytes. This means that the characters encoded with 4-6 bytes in the Unicode supplementary planes are not supported.

5. Date Format

All date objects follow the format defined in 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

6. Unique Identifier of the Request

WeChat Pay assigns a unique identifier to each received request. The unique ID of a request is included in Request-ID in the HTTP header of the response. Please provide the unique ID of the request if you need any help, so that we can locate the request quickly.

7. Error Information

WeChat Pay API V3 uses an HTTP status code to indicate the request result.

• For a successful request, the code 200 is returned if the message body has a response, and 204 is returned if the message body has no response.

• For a request which has been accepted for processing, 202 is returned.

• For a failed request, if the failure is caused by such reasons as missing input parameters or insufficient balance, an error code 4xx is returned.

• If an error occurs with the service system on the WeChat Pay side when a request is processed, an error code of 500, 501, or 503 is returned. This is a rare case.

8. Error Code and Message

In case of a failure of API request, an error description is returned in the message body along with the HTTP status code.

• code：Error code

• message：A short error description indicating the reason for the error.

• field: Indicates the location of the incorrect parameter. If the incorrect parameter is in the JSON for request body, it is populated with theJSON Pointer pointing to this parameter. If the incorrect parameter is in the request URL or querystring, it is populated with the variable name of this parameter.

• value:The incorrect value.

• issue:Detailed reason for the error.

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

9. User Agent

According to the HTTP protocol, the client initiating the request must include User-Agent in the HTTP header of each request to identify itself. The caller can use either of the following two methods:

1.Use the default User-Agent of the HTTP client.

2.Use a custom User-Agent which is a combination of such information as the system name, App name, and version by following the HTTP protocol.

WeChat Pay API V3 is likely to reject a request without User-Agent.

10. Response Language

A WeChat Pay REST API allows the caller to declare the natural language used in the error description in the response. If necessary, Accept-Language in the HTTP header should be set for the request. Supported languages:

• en

• zh-CN

• zh-HK

• zh-TW

If the Accept-Language is not set or supported, Simplified Chinese (zh-CN) is used.