微信JSAPI支付是公众号内完成收款的主流方式，整个链路分为两步：后端调用统一下单接口获取prepay_id，前端再用wx.chooseWXPay或WeixinJSBridge调起支付。其中第二步需要用第一步返回的数据重新计算一次签名（paySign），而签名的计算依赖商户平台的API密钥。如果商户号从未配置过密钥，或者密钥配置的是v3而代码按v2方式签名，统一下单就会直接报错，前端自然无法调起支付。本文将从原理到实操，完整讲解这个问题的排查与解决。
一、理解签名链路：为什么密钥缺失会导致调起失败
很多开发者以为JSAPI调起失败是前端问题，实际上支付签名有两个关键环节。第一个环节是后端调用统一下单接口时，请求参数本身需要用API密钥（v2的MD5或HMAC-SHA256签名，或v3的RSA私钥签名）参与计算sign字段；第二个环节是统一下单成功后，后端用返回的prepay_id再生成一次paySign给前端使用。
如果商户号没有配置API密钥，第一个环节就会失败。此时统一下单接口通常返回SIGN_ERROR或提示“签名错误”，甚至直接提示需要到商户平台设置密钥。后端拿不到prepay_id，返回给前端的数据就是空的或者错误的，前端调用wx.chooseWXPay时表现为参数格式错误、调不起支付窗口，或弹出“支付验证失败”。
还有一种更隐蔽的情况：商户号配置的是APIv3密钥（32位字符串，仅用于解密回调和解密证书），但代码用的是v2统一下单接口且用v3密钥去做MD5签名，同样会导致签名校验失败。v2密钥在账户中心的API安全中设置，v3密钥是另一项独立配置，两者不能混用。
二、商户平台配置API密钥的正确步骤
登录微信商户平台pay.weixin.qq.com，进入“账户中心”下的“API安全”页面。这里分两个配置项：API密钥（v2）和APIv3密钥。如果使用v2接口（XML格式、MD5签名的统一下单），必须设置API密钥；如果使用v3接口（JSON格式、RSA签名），则需要下载API证书并设置APIv3密钥。
设置密钥时需要注意几点：密钥长度必须是32位字符，建议由大小写字母和数字随机组成；密钥设置后立即生效，但部分老版本接口可能有短暂缓存；操作时需要管理员手机验证码确认。密钥一旦遗忘无法查询，只能重新设置，重新设置后所有依赖旧密钥的签名都会失效，需要同步更新代码中的配置。
配置完成后，建议用最简单的参数先在服务器上直接curl一次统一下单接口验证，确认不再返回签名错误，再回到业务代码中排查。这样可以避免密钥问题和代码问题混在一起，越查越乱。
三、后端签名代码实现示例
下面以Java为例，演示v2统一下单的核心签名逻辑。签名规则是：将所有非空参数按key的ASCII码升序排列，拼接成key1=value1&key2=value2的形式，最后拼上&key=商户密钥，再进行MD5运算并转大写。
import java.util.*;
public class WxPaySignUtil {
/**
* 生成微信支付v2签名
* params 业务参数，key 商户平台设置的32位API密钥
*/
public static String createSign(Map<String, String> params, String key) {
// 按key的ASCII码升序排序，排除sign和空值字段
SortedMap<String, String> sorted = new TreeMap<>(params);
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> entry : sorted.entrySet()) {
String k = entry.getKey();
String v = entry.getValue();
if (v == null || v.isEmpty() || "sign".equals(k)) {
continue;
}
sb.append(k).append("=").append(v).append("&");
}
// 末尾拼上密钥
sb.append("key=").append(key);
return md5Hex(sb.toString()).toUpperCase();
}
private static String md5Hex(String s) {
try {
java.security.MessageDigest md = java.security.MessageDigest.getInstance("MD5");
byte[] digest = md.digest(s.getBytes("UTF-8"));
StringBuilder hex = new StringBuilder();
for (byte b : digest) {
String h = Integer.toHexString(b & 0xFF);
if (h.length() == 1) hex.append("0");
hex.append(h);
}
return hex.toString();
} catch (Exception e) {
throw new RuntimeException(e);
}
}
}统一下单成功拿到prepay_id后，给前端生成paySign时同样调用createSign方法，只是参数换成appId、timeStamp、nonceStr、package（值为prepay_id=xxx）、signType。注意package的值不是json，是固定格式字符串。
如果使用v3接口，签名方式完全不同：需要用商户私钥对请求串做SHA256withRSA签名放在Authorization头中，APIv3密钥只用于AES-256-GCM解密支付回调报文，两者职责不要搞混。
四、常见报错排查清单
密钥类问题在日志中往往表现为固定几种报错，逐条对照可以快速定位：
- 统一下单返回SIGN_ERROR：优先检查密钥是否已设置、代码中的密钥是否与商户平台一致、是否混用了v2和v3密钥。
- 统一下单返回“参数错误，请检查字段是否符合格式”：检查body、out_trade_no等必填字段，以及total_fee是否以分为单位的整数。
- 前端调起时报“支付验证失败”：多半是paySign计算有误，重点检查签名参数是否用了timeStamp、nonceStr与实际传给前端的一致，package格式是否正确。
- 提示“当前页面的URL未注册”：这不是签名问题，是支付授权目录未配置，需在商户平台的产品中心JSAPI支付中添加调用页面所在目录。
排查时建议在后端把统一下单的请求报文、返回报文完整打印出来（注意脱敏密钥），先确认prepay_id是否正常返回，再看前端参数是否与签名时一致。绝大多数“调起失败”问题，顺着这两步走一遍就能定位到密钥配置或签名算法的环节。解决后，建议将密钥存放在配置中心或环境变量中，避免硬编码在代码里，也方便后续轮换。