接口规则

更新时间:2025.03.24

协议规则

商户接入微信支付,调用API必须遵循以下规则:

传输方式

为保证交易安全性,采用HTTPS传输

提交方式

采用POST方法提交

数据格式

提交和返回数据都为XML格式,根节点名为xml

字符编码

统一采用UTF-8字符编码

签名算法

MD5,后续会兼容SHA1、SHA256、HMAC等。

签名要求

请求和接收数据均需要校验签名,详细方法请参考安全规范-签名算法

证书要求

调用申请退款、撤销订单接口需要商户证书

判断逻辑

先判断协议字段返回,再判断业务返回,最后判断交易状态

安全规范

1、签名算法

签名生成的通用步骤如下:

第一步,设所有发送或者接收到的数据为集合M,将集合M内非空参数值的参数按照参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA。

特别注意以下重要规则:

◆ 参数名ASCII码从小到大排序(字典序);

◆ 如果参数的值为空不参与签名;

◆ 参数名区分大小写;

◆ 验证调用返回或微信主动通知签名时,传送的sign参数不参与签名,将生成的签名与该sign值作校验。

◆ 微信接口可能增加字段,验证签名时必须支持增加的扩展字段

 

第二步,在stringA最后拼接上key得到stringSignTemp字符串,并对stringSignTemp进行MD5运算,再将得到的字符串所有字符转换为大写,得到sign值signValue。

◆ key设置路径:微信商户平台(pay.weixin.qq.com)-->账户中心-->账户设置-->API安全-->设置API密钥

举例:

假设传送的参数如下:

1appid:wxd930ea5d5a258f4f
2mch_id:10000100
3device_info:1000
4body:test
5nonce_str:ibuaiVcKdpRxkhJA
6

第一步:对参数按照key=value的格式,并按照参数名ASCII字典序排序如下:

1stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA";
2

第二步:拼接API密钥:

1stringSignTemp=stringA+"&key=192006250b4c09247ec02edce69f6a2d" //注:key为商户平台设置的密钥key
2sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7" //注:MD5签名方式
3sign=hash_hmac("sha256",stringSignTemp,key).toUpperCase()="6A9AE1657590FD6257D693A078E1C3E4BB6BA4DC30B23E0EE2496E54170DACD6" //注:HMAC-SHA256签名方式
4

最终得到最终发送的数据:

1<xml>
2  <appid>wxd930ea5d5a258f4f</appid>
3  <mch_id>10000100</mch_id>
4  <device_info>1000</device_info>
5  <body>test</body>
6  <nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
7  <sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign>
8</xml>                        
9

2、生成随机数算法

微信支付API接口协议中包含字段nonce_str,主要保证签名不可预测。我们推荐生成随机数算法如下:调用随机数函数生成,将得到的值转换为字符串。

 

3、API证书

(1)获取API证书(什么是api证书?如何升级?

微信支付接口中,涉及资金回滚的接口会使用到API证书,包括退款、撤销接口。商家在申请微信支付成功后,收到的相应邮件后,可以按照指引下载API证书,也可以按照以下路径下载:微信商户平台(pay.weixin.qq.com)-->账户中心-->账户设置-->API安全 。证书文件说明如下:

证书附件

描述

使用场景

备注

pkcs12格式
(apiclient_cert.p12)

包含了私钥信息的证书文件,为p12(pfx)格式,由微信支付签发给您用来标识和界定您的身份

撤销、退款申请API中调用

windows上可以直接双击导入系统,导入过程中会提示输入证书密码,证书密码默认为您的商户ID(如:10010000)

以下两个证书在PHP环境中使用:

证书附件

描述

使用场景

备注

证书pem格式
(apiclient_cert.pem)

从apiclient_cert.pem中导出证书部分的文件,为pem格式,请妥善保管不要泄露和被他人复制

PHP等不能直接使用p12文件,而需要使用pem,为了方便您使用,已为您直接提供

您也可以使用openssl命令来自己导出:openssl pkcs12 -clcerts -nokeys -in apiclient_cert.pem -out apiclient_cert.pem

证书密钥pem格式
(apiclient_key.pem)

从apiclient_key.pem中导出密钥部分的文件,为pem格式,请妥善保管不要泄露和被他人复制

PHP等不能直接使用p12文件,而需要使用pem,为了方便您使用,已为您直接提供

您也可以使用openssl命令来自己导出:openssl pkcs12 -nocerts -in apiclient_cert.pem -out apiclient_key.pem

(2)使用API证书

◆ apiclient_cert.p12是商户证书文件,除PHP外的开发均使用此证书文件。

◆ 商户如果使用.NET环境开发,请确认Framework版本大于2.0,必须在操作系统上双击安装证书apiclient_cert.p12后才能被正常调用。

◆ API证书调用或安装需要使用到密码,该密码的值为微信商户号(mch_id)

 

(3)API证书安全

◆ 证书文件不能放在web服务器虚拟目录,应放在有访问权限控制的目录中,防止被他人下载;

◆ 建议将证书文件名改为复杂且不容易猜测的文件名;

◆ 商户服务器要做好病毒和木马防护工作,不被非法侵入者窃取证书文件。

 

4、商户回调API安全

在普通的网络环境下,HTTP请求存在DNS劫持、运营商插入广告、数据被窃取,正常数据被修改等安全风险。商户回调接口使用HTTPS协议可以保证数据传输的安全性。所以微信支付建议商户提供给微信支付的各种回调采用HTTPS协议。请参考:HTTPS搭建指南。

 

5、获取openid

openid是微信用户在公众号appid下的唯一用户标识(appid不同,则获取到的openid就不同),可用于永久标记一个用户,同时也是微信JSAPI支付的必传参数。

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.