---
url: "https://pay.weixin.qq.com/doc/v3/merchant/4012081709.md"
title: "基本规则"
doc_id: 4012081709
---

>更新时间：2024.07.25

## 基本信息

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

请求时不应忽略服务器证书验证的错误，避免被恶意劫持。

## 数据格式

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

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

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

提示

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

## 参数兼容性

- 请求是否成功，与请求参数的顺序无关

- 请求是否成功，与请求JSON中的键值对出现的顺序无关

- 处理应答时，不应假设应答JSON中的键值对出现的顺序

- 新的API版本可能在请求或应答中加入新的参数或者JSON的键值对

- 新的API版本不会去除请求和应答中已经存在的必填参数或者JSON的键值对

- 参数使用 JSON 的数据类型：integer、boolean、string、object 和 array，不允许使用 null


## 字符集

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

## 日期格式

所有的日期对象，使用 [ISO 8601](https://datatracker.ietf.org/doc/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状态码](https://pay.weixin.qq.com/doc/v3/merchant/4012081717.md)表示错误之外，API响应体将返回结构化的错误信息，用于明确说明错误原因，关于错误信息的解决方案请参考对应的API接口文档。

- code：错误码，分为​​公共错误码​​和​​业务错误码​​，详见下方示例。

- message：错误描述，详细说明当前报错的具体原因，同一code（错误码）可能对应多个不同的message（错误描述）。


公共错误码

|     |     |
| --- | --- |
| 错误码 | 错误描述 |
| PARAM\_ERROR | 参数错误 |
| INVALID\_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 |
| SIGN\_ERROR | 验证不通过 |
| SYSTEM\_ERROR | 系统异常，请稍后重试 |

```
//公共错误码返回示例
{
  "code": "SYSTEM_ERROR",
  "message": "系统异常，请稍后重试"
}
```

业务错误码（此处仅为示例，实际以API接口文档为准）

|     |     |
| --- | --- |
| 错误码 | 错误描述 |
| NO\_AUTH | 商户无权限 |
| OUT\_TRADE\_NO\_USED | 商户订单号重复 |

```
//业务错误码返回示例
{
  "code": "NO_AUTH",
  "message": "商户号该产品权限未开通，请前往商户平台>产品中心检查后重试"
}
```

- detail：错误的具体情况，当 code 为 PARAM\_ERROR 或 INVALID\_REQUEST 时返回。

  - field：指示错误参数的具体位置，当错误参数位于请求Body的JSON中，返回[JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901)路径 (如：/amount/currency)；当错误参数位于请求的 URL 或者 Query String 中，返回参数变量名(如：limit)；

  - value：错误的值；

  - issue：具体错误原因；

  - location：错误参数的来源位置，取值如下：

    - body：错误参数位于请求 Body 的 JSON 中；

    - url：错误参数位于请求 URL 中；

    - query：错误参数位于请求的 Query String 中；

```
//detail返回示例
{
  "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）。