基本规则
更新时间:2024.10.301. 基本信息
所有的API请求必须使用HTTPS。
|
2. 数据格式
所有的API请求必须使用HTTPS。
|
图片上传API除外。
|
3. 参数兼容性
请求是否成功,与请求参数的顺序无关
请求是否成功,与请求JSON中的键值对出现的顺序无关
处理应答时,不应假设应答JSON中的键值对出现的顺序
新的API版本可能在请求或应答中加入新的参数或者JSON的键值对
新的API版本不会去除请求和应答中已经存在的必填参数或者JSON的键值对
当请求或应答中的JSON键值对的值为空(null)时,可以省略
4. 字符集
微信支付API V3仅支持UTF-8字符编码的一个子集:使用一至三个字节编码的字符。也就是说,不支持Unicode辅助平面中的四至六字节编码的字符。
5. 日期格式
所有的日期对象,使用 ISO 8601 所定义的格式。示例:
6. 请求的唯一标识
微信支付给每个接收到的请求分配了一个唯一标识。请求的唯一标识包含在应答的HTTP头Request-ID中。当需要微信支付帮助时,请提供请求的唯一标识,以便我们更快的定位到具体的请求。
7. 错误信息
微信支付API V3使用HTTP状态码来表示请求处理的结果。
处理成功的请求,如果有应答的消息体将返回200,若没有应答的消息体将返回204。
已经被成功接受待处理的请求,将返回202。
请求处理失败时,如缺少必要的入参、支付时余额不足,将会返回4xx范围内的错误码。
请求处理时发生了微信支付侧的服务系统错误,将返回500/501/503的状态码。这种情况比较少见。
8. 错误码和错误提示
当请求处理失败时,除了HTTP状态码表示错误之外,API将在消息体返回错误相应说明具体的错误原因。
code
:详细错误码
message
:错误描述,使用易理解的文字表示错误的原因。
field
: 指示错误参数的位置。当错误参数位于请求body的JSON时,填写指向参数的JSON Pointer 。当错误参数位于请求的url或者querystring时,填写参数的变量名。
value
:错误的值
issue
:具体错误原因
9. User Agent
HTTP协议要求发起请求的客户端在每一次请求中都使用HTTP头 User-Agent
来标识自己。微信支付建议调用方选用以下两种方式的一种:
1.使用HTTP客户端默认的 User-Agent
。
2.遵循HTTP协议,使用自身系统和应用的名称和版本等信息,组成自己独有的User-Agent
。
微信支付API V3很可能会拒绝处理无User-Agent
的请求。
10. 应答的语种
微信支付API V3允许调用方声明应答中的错误描述使用的自然语言语种。如果有需要,设置请求的HTTP头Accept-Language
。目前支持:
en
zh-CN
zh-HK
zh-TW
当不设置或者值不支持时,将使用简体中文(zh-CN)。