API升级指引

1. 背景说明

为了带给商户简单、一致且易用的开发体验，微信支付目前推出了可供全球机构/商户使用的API V3，该版本API的具体规则请参考“APIv3接口规则”。

对于新入驻的微信支付机构/商户，请参考API v3 Global文档中心各产品的接入前准备，开发指引来完成对接。

非香港地区的已接入机构/商户，默认使用的API版本为API v2，后续可根据自身情况选择是否要对已接入API进行升级，若选择保持使用v2，可通过API v2文档中心查看相关文档。如选择升级，请参考以下升级及注意事项说明完成API升级。

说明

API升级并非强制行为，机构可根据自身的实际需求及情况选择是否升级，原API v2仍可继续使用。

注意

对于香港地区已接入API v3 HK的机构和商户，后续的产品接入请参考API v3 Global的相关文档，原API v3 HK可继续使用，但对应文档会逐步下架。

说明

API v3 HK与API v3 Global仅各API的请求地址存在差异，其他均保持一致，详情请参考API v3 Global文档中心。

2. 接口版本对比

与当前使用的XML+MD5的API v2接口相比，新的API v3 Global的产品接入流程及产品业务流程并没有发生变化，主要的区别点在于API的协议差异，以下为具体差异对比：

3. 参数说明

appid：已入驻且已对接API v2的机构/商户，若需要升级到API V3，可继续使用已有的公众号appid，不需要做额外的更换或升级。

mch_id：与appid情况一致，可继续使用已有的Mch_id，不需要重新申请或升级。

sub_mch_id：子商户号同样不需要重新申请或升级，可直接使用。

sub_appid：子商户appid也不需要重新申请或升级，可直接使用。

API key：该参数在API V3中不会使用，已设置的api key可以在商户升级API灰度过程中保留。

API key v3：API V3新增开发参数，主要用于敏感信息的加密和解密，具体用途及用法请参考“加密解密”，设置方式请参考“API V3 key设置指引”。

证书：API V3的调用，需要使用CA签发的证书，请先登录商户平台，进入account settings→API security目录，查看API certificate项，若界面如下图所示，则代表该商户号对应证书已经升级到CA证书，可直接对接API V3。 若界面如下图所示，则代表当前商户号使用证书为自签证书，若想要调用API V3，则必须先对证书进行升级，点击界面中的Upgrade，然后参考“API证书下载”进行升级。

注意

证书升级后，并不影响当前API v2的使用，API v2接口的调用也可以使用升级后的CA证书。

证书升级后，新老证书有14天的共同有效期，14天后，老证书将过期失效，所以请及时将新证书部署到系统内。

4. 权限申请

API V3不需要额外的权限申请，仅需完成API V3 key的设置及证书升级后即可开始API V3的对接开发。

5. 其他注意事项

未来微信支付新增的能力都将使用API V3协议，建议机构/商户优先选择API V3进行业务对接。