# 接口规则

## 基本信息

所有的API请求必须使用HTTPS。

{% hint style="warning" %}
请求时不应忽略服务器证书验证的错误，避免被恶意劫持
{% endhint %}

### 数据格式

微信支付API v3使用[JSON](http://www.json.org/)作为消息体的数据交换格式。请求须设置HTTP头部：

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

图片上传API除外。

{% hint style="danger" %}
 API应答中的数据有可能包含商户传入的数据，即可能是未经检查的用户输入内容。为了避免XSS（Cross-site scripting）攻击，请调用方在使用应答数据前根据场景做适当的转义或者过滤。
{% endhint %}

### 参数兼容性

* 请求是否成功，与请求参数的顺序无关
* 请求是否成功，与请求JSON中的键值对出现的顺序无关
* 处理应答时，不应假设应答JSON中的键值对出现的顺序
* 新的API版本可能在请求或应答中加入新的参数或者JSON的键值对
* 新的API版本不会去除请求和应答中已经存在的必填参数或者JSON的键值对
* 当请求或应答中的JSON键值对的值为空（null）时，可以省略

### 字符集

微信支付API v3仅支持**UTF-8**字符编码的一个子集：使用一至三个字节编码的字符。也就是说，不支持Unicode辅助平面中的四至六字节编码的字符。

### 日期格式

所有的日期对象，使用[ISO 8601](https://tools.ietf.org/html/rfc3339)所定义的格式。示例：

```
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
```

### 请求的唯一标示

微信支付给每个接收到的请求分配了一个唯一标示。请求的唯一标示包含在应答的HTTP头`Request-ID`中。**当需要微信支付帮助时，请提供请求的唯一标示，以便我们更快的定位到具体的请求。**

## 错误信息

微信支付API v3使用HTTP状态码来表示请求处理的结果。

* 处理成功的请求，如果有应答的消息体将返回200，若没有应答的消息体将返回204。
* 已经被成功接受待处理的请求，将返回202。
* 请求处理失败时，如缺少必要的入参、支付时余额不足，将会返回4xx范围内的错误码。
* 请求处理时发生了微信支付侧的服务系统错误，将返回500/501/503的状态码。这种情况比较少见。

### HTTP状态码

常见的HTTP状态码见下表。

| 状态码                       | 错误类型         | 一般的解决方案                 | 典型错误码示例              |
| ------------------------- | ------------ | ----------------------- | -------------------- |
| 200 - OK                  | 处理成功         |                         |                      |
| 204 - No Content          | 处理成功，无返回Body |                         |                      |
| 400 - Bad Request         | 协议或者参数非法     | 请根据接口返回的详细信息检查您的程序      | PARAM\_ERROR         |
| 401 - Unauthorized        | 签名验证失败       | 请检查签名参数和方法是否都符合签名算法要求   | SIGN\_ERROR          |
| 403 - Forbidden           | 权限异常         | 请开通商户号相关权限。请联系产品或商务申请   | NO\_AUTH             |
| 404 - Not Found           | 请求的资源不存在     | 请商户检查需要查询的id或者请求URL是否正确 | ORDER\_NOT\_EXIST    |
| 429 - Too Many Requests   | 请求超过频率限制     | 请求未受理，请降低频率后重试          | RATELIMIT\_EXCEEDED  |
| 500 - Server Error        | 系统错误         | 按具体接口的错误指引进行重试          | SYSTEM\_ERROR        |
| 502 - Bad Gateway         | 服务下线，暂时不可用   | 请求无法处理，请稍后重试            | SERVICE\_UNAVAILABLE |
| 503 - Service Unavailable | 服务不可用，过载保护   | 请求无法处理，请稍后重试            | SERVICE\_UNAVAILABLE |

### 错误码和错误提示

当请求处理失败时，除了HTTP状态码表示错误之外，API将在消息体返回错误相应说明具体的错误原因。

* `code`：详细错误码
* `message`：错误描述，使用易理解的文字表示错误的原因。
* `field`：指示错误参数的位置。当错误参数位于请求body的JSON时，填写指向参数的[JSON Pointer](https://tools.ietf.org/html/rfc6901)。当错误参数位于请求的url或者querystring时，填写参数的变量名。
* `value`：错误的值
* `issue`：具体错误原因

```javascript
{
  "code": "PARAM_ERROR",
  "message": "参数错误",
  "detail": {
    "field": "/amount/currency",
    "value": "XYZ",
    "issue": "Currency code is invalid",
    "location" :"body"
  }
}
```

## User Agent

HTTP协议要求发起请求的客户端在每一次请求中都使用HTTP头`User-Agent`来标示自己。微信支付建议调用方选用以下两种方式的一种：

1. 使用HTTP客户端默认的`User-Agent`。
2. 遵循HTTP协议，使用自身系统和应用的名称和版本等信息，组成自己独有的`User-Agent`。

微信支付API v3很可能会拒绝处理无`User-Agent`的请求。

## 应答的语种

微信支付API v3允许调用方声明应答中的错误描述使用的自然语言语种。如果有需要，设置请求的HTTP头`Accept-Language`。目前支持：

* en
* zh-CN
* zh-HK
* zh-TW

当不设置或者值不支持时，将使用简体中文（zh-CN）。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wechatpay-api.gitbook.io/wechatpay-api-v3/wei-xin-zhi-fu-api-v3-jie-kou-gui-fan.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.