微信支付的 v2 和 v3 接口有什么区别

微信商户平台里同时存在「API 密钥」和「APIv3 密钥」两套材料，对应微信支付的两代接口。本页讲清两代的区别、Darkroom 使用哪一代，以及你实际需要设置哪些、可以不管哪些。

在微信支付商户平台的「账户中心 → API安全」里，你会看到两组名字很像、用途却完全不同的材料。很多品牌管理员在这里卡住：到底哪些是必须设的，哪些可以不管？

本页解释这个结论背后的原因，以及几种常见情况怎么处理。

一、v2 和 v3 是什么

它们是微信支付先后推出的两代接口协议。

「接口协议」的意思是：Darkroom 的系统替你向微信发起收款请求时，双方约定好的一套对话格式——请求写成什么样、怎么证明这条请求真的来自你、微信怎么把结果告诉回来。

微信早年推出的那一代叫 v2，后来推出的新一代叫 v3。两代都由微信正式支持、都在跑真实交易，不是「旧的已废弃、新的才能用」的关系。任何一个接商户平台的系统，会挑其中一代实现，然后一直用那一代——两代的对话格式完全不同，不能混着说话。

这就是为什么商户平台上会并列摆着两套材料：微信不知道你会接入哪种系统，所以两代的材料都给你留了设置入口。你的系统用哪一代，你就设哪一代的材料。

	v2（Darkroom 使用）	v3
怎么证明请求来自你	用你设的 API 密钥给请求算一个校验码	用商户 API 证书里的私钥给请求做数字签名
微信怎么告诉你收款结果	直接把结果发过来，附一个校验码供核对	把结果加密后发过来，你得先解密才能读
因此需要准备	API 密钥（一串 32 位字符）商户 API 证书（退款时用）	商户 API 证书 APIv3 密钥（解密用）微信支付公钥（验证微信身份用）

一眼就能看出：v3 需要准备的材料比 v2 多两样，多出来的 APIv3 密钥和微信支付公钥，正是为了支撑「加密传输」这套更复杂的机制。

主要原因是：这条链路上跑着真金白银，而它已经稳定运行了很多年。

Darkroom 的收款、付款结果确认、退款三条链路都是按 v2 实现并长期验证过的。把它们改成 v3，等于把已经在正常收钱的管道整段换掉——收益是协议更现代，代价是在换的过程中一旦出错，直接表现为顾客付不了款或者钱收不到。这笔账我们认为现在不划算。

对你来说，这个选择的实际影响只有一个：少设一把密钥、少交两样材料。 收款能力、到账速度、手续费、可用的支付方式，都和接口版本无关，不受影响。

我已经设过 APIv3 密钥了，要删掉吗？

不用，留着就行。它设了但没人用，不会造成任何问题，也不会影响收款。真要清理，在商户平台重置它也不会波及 Darkroom——我们从不读它。

我能不能只设一把密钥，两个框填同一个值？

技术上微信允许，但强烈不建议。两把密钥都是 32 位字符串、长得一模一样，一旦设成同值，你自己以后就分不清哪个是哪个了；更麻烦的是，将来任何一方泄露，另一方也跟着失守。

正确做法是：只设「API 密钥」这一个，「APIv3 密钥」那个框空着不动。 如果你出于别的原因需要两个都设，那就设成两个不同的值。

填错框会怎样？

这是这一块最常见、也最难自己发现的错误：把 APIv3 密钥的值填进了 API 密钥的框。两者长得一样，肉眼看不出问题，但对微信来说等于用错了钥匙——所有收款请求都会被拒绝，微信返回的报错通常只有含糊的一句「签名错误」，看不出真正的原因。

设置时盯紧商户平台上的按钮文字：「设置API密钥」和「设置APIv3密钥」是两个不同的按钮。你要点的是前者。

以后 Darkroom 会升级到 v3 吗？

有可能，但目前没有时间表。如果那天到来，我们会提前通知你需要补交哪些材料，并安排在不影响收款的时段完成切换——不会出现「你没做任何操作，收款突然失败」的情况。

别的系统问我要 APIv3 密钥，能给吗？

那是它们自己的接入需要，和 Darkroom 无关，你按各自的要求处理即可。只要记住一点：任何密钥和证书都只应通过对方官方的后台页面提交，不要用微信、邮件或工单截图发送。 Darkroom 的工作人员也不会通过聊天向你索要这些材料。