基本规则

更新时间：2025.11.11

基本信息

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

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

数据格式

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

微信支付品牌API使用 JSON 作为消息体的数据交换格式。请求须设置HTTP头部（图片上传API除外）：

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

提示

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

参数兼容性

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

字符集

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

日期格式

所有的日期对象，使用 RFC3339 所定义的格式。

示例：

1yyyy-MM-DDTHH:mm:ss.SSSZ
2yyyy-MM-DDTHH:mm:ssZ
3yyyy-MM-DDTHH:mm:ss.SSS+08:00
4yyyy-MM-DDTHH:mm:ss+08:00

请求的唯一标识

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

应答的HTTP头信息示例：

1Content-Type: application/json; charset=utf-8
2Content-Length: 46
3Connection: keep-alive
4Keep-Alive: timeout=8
5Cache-Control: no-cache, must-revalidate
6X-Content-Type-Options: nosniff
7Request-ID: 8C8CD84C606104018CFB0BCA801200228E69801-0   //请求的唯一标识，建议在日志中保留该数据
8Content-Language: zh-CN
9Wechatpay-Nonce: e63973074d9d78aff8fb62277b5f95a0
10Wechatpay-Signature: X1Gn3pQoWOZ3wxon98uBwv3/XieeN/TnPLi2ovdeBxl54mBrxcpCYiE+VhYWhNu9MOt6a768y9X5c/VwAPvznskpOqeXqTSLMv0MmfQGyF4SszElhPknkyFySrrSM9BQngzATR+dIMmDoeAzvmnDmUZDtAzao4xvvrnfUuogF3aTTyONPw56dIt+V4sBjuQsArdufd8h+mjzMCoegQ8ZMx2he5kEFY3RHEgQiP0VJq036MwRugauHNVt/lSnKvCblRwxKMtzqPpbyFzP8f8hF1y0teWzVt/WzWWGRsR9cnJ6c6viYJrCawCxTaPdyPasOaj/7DgyHwdQDroKEx1GnA==
11Wechatpay-Timestamp: 1757488840
12Wechatpay-Serial: PUB_KEY_ID_1652966817968711769710052651413695
13Wechatpay-Signature-Type: WECHATPAY-BRAND-SHA256-RSA2048

错误信息

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

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

错误码和错误提示

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

code：详细错误码；
message：错误描述，使用易理解的文字表示错误的原因；
field：指示错误参数的位置。当错误参数位于请求body的JSON时，填写指向参数的JSON Pointer 。当错误参数位于请求的URL或者querystring时，填写参数的变量名；
value：错误的值；
issue：具体错误原因。

1{
2  "code": "PARAM_ERROR",
3  "message": "参数错误",
4  "detail": {
5    "field": "/amount/currency",
6    "value": "XYZ",
7    "issue": "Currency code is invalid",
8    "location" :"body"
9  }
10}

User Agent

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

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

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

应答的语种

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

en
zh-CN
zh-HK
zh-TW

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

文档是否有帮助

更多支持

开发者社区微信开放平台微信公众平台腾讯客服