接入微信小程序支付并非简单调用几个API,而是一套严谨的业务与安全体系。开发者需依次完成以下关键环节:
pay.weixin.qq.com商户平台 →「产品中心」→「开发配置」→ 开通「小程序」支付能力weixin-java-pay):<dependency>
<groupId>com.github.binarywang</groupId>
<artifactId>weixin-java-pay</artifactId>
<version>4.5.0</version>
</dependency>
wx.requestPayment 前,需先向后端(Java服务)发起「统一下单」请求POST /v3/pay/transactions/jsapi,传入:appid、mchid(商户号)description(商品描述,如:「XServX小程序订单-123456」)out_trade_no(商户订单号,唯一)amount.total(订单总金额,单位:分)payer.openid(用户在小程序的唯一标识)notify_url(异步通知地址)prepay_id(预支付交易会话标识)appId、timeStamp、nonceStr、package、signType、paySign)并返回给前端wx.requestPayment({...}) 发起支付<xml><return_code>SUCCESS</return_code></xml>WxPayV3Service payService = new WxPayV3ServiceImpl();
payService.setMchId("190000***");
payService.setMchPrivateKey("-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASC...\n-----END PRIVATE KEY-----\n");
payService.setApiV3Key("your-api-v3-key-32chars");
JsapiRequest request = new JsapiRequest();
request.setAppid("wxa1b2c3d4e5f6g7h8");
request.setMchid("190000***");
request.setDescription("XServX小程序订单-20260405001");
request.setOutTradeNo("TX" + System.currentTimeMillis());
request.setAmount(new Amount().setTotal(100)); // 1元 = 100分
request.setPayer(new Payer().setOpenid("oUpF8uMuA2_Mb3V6bI6rQ019N5Ag"));
request.setNotifyUrl("https://www.xservx.com/api/pay/notify");
try {
JsapiResponse response = payService.jsapi(request);
// 构造前端所需签名参数
String prepayId = response.getPrepayId();
String timeStamp = String.valueOf(System.currentTimeMillis() / 1000);
String nonceStr = WxPayAPI.generateNonceStr();
String packageStr = "prepay_id=" + prepayId;
String signType = "RSA";
String paySign = WxPaySignature.sign(
new String[]{ "appId", "timeStamp", "nonceStr", "package", "signType" },
new String[]{ request.getAppid(), timeStamp, nonceStr, packageStr, signType },
payService.getApiV3Key()
);
Map<String, String> result = new HashMap<>();
result.put("appId", request.getAppid());
result.put("timeStamp", timeStamp);
result.put("nonceStr", nonceStr);
result.put("package", packageStr);
result.put("signType", signType);
result.put("paySign", paySign);
return ResponseEntity.ok(result);
} catch (Exception e) {
log.error("统一下单失败", e);
return ResponseEntity.status(500).body(Map.of("error", e.getMessage()));
}
wx.request({
url: 'https://www.xservx.com/api/pay/unified-order',
method: 'POST',
data: { orderId: '20260405001' },
success(res) {
if (res.data.error) {
wx.showToast({ title: res.data.error, icon: 'none' });
return;
}
wx.requestPayment({
timeStamp: res.data.timeStamp,
nonceStr: res.data.nonceStr,
package: res.data.package,
signType: res.data.signType,
paySign: res.data.paySign,
success: function(res) {
wx.showToast({ title: '支付成功', icon: 'success' });
// 可选:跳转至订单详情页
},
fail: function(err) {
if (err.errMsg !== 'requestPayment:fail cancel') {
wx.showToast({ title: '支付失败', icon: 'none' });
}
}
});
}
});
微信支付V3 API是基于HTTPS+JSON的RESTful接口,采用RFC 7517标准的JWT签名机制,彻底取代旧版V2的MD5/SHA1签名体系。其核心优势在于:更强的安全性、更清晰的资源层次、更规范的错误码体系。
| 接口名称 | 路径 | 用途 | Java SDK方法 |
|---|---|---|---|
| 统一下单(JSAPI) | /v3/pay/transactions/jsapi | 创建订单,获取prepay_id | jsapi(request) |
| 查询订单 | /v3/pay/transactions/out-trade-no/{out_trade_no} | 通过商户订单号查支付状态 | queryOrderByOutTradeNo(outTradeNo) |
| 关闭订单 | /v3/pay/transactions/out-trade-no/{out_trade_no}/close | 订单超时未支付时主动关闭 | closeOrder(outTradeNo) |
| 申请退款 | /v3/refund/domestic/refunds | 发起退款请求 | refund(request) |
| 查询退款 | /v3/refund/domestic/refunds/{refund_id} | 查退款状态 | queryRefundById(refundId) |
| 下载账单 | /v3/bill/downloadfile?bill_date=2026-04-05 | 获取交易账单(需申请权限) | downloadBill(billDate) |
所有V3请求必须携带以下Header(由SDK自动处理,但理解原理至关重要):
Authorization: Bearer mchid_xxx:timestamp_xxx:nonce_xxx:signature_xxxAccept: application/jsonContent-Type: application/json其中Bearer部分为JWT Token,结构为:
{mch_id}:{timestamp}:{nonce_str}:{signature}
签名算法:
signature = sign(RSA_SHA256, message, merchant_private_key)
其中message = http_method + "\n" + uri + "\n" + timestamp + "\n" + nonce_str + "\n" + body_hash + "\n"
body_hash = SHA256_HEX(body)
V3 API统一返回HTTP状态码 + JSON格式错误信息:
{
"code": "INVALID_REQUEST",
"message": "请求参数格式错误",
"detail": {
"field": "amount.total",
"issue": "订单金额必须为整数且大于0"
}
}
Java中应捕获WxPayException并解析错误码:
catch (WxPayException e) {
log.error("支付错误 [{}]: {}", e.getErrorCode(), e.getMessage());
log.debug("详细信息: {}", e.getErrorDetail());
// 根据错误码做不同处理:如重复订单号(ORDER_REPEAT)、金额不足(PAY_AMOUNT_LIMIT)等
}
101.226.240.0/24)WxPayService.checkNotification()验签,禁止直接信任客户端数据idempotency_key防止重复提交签名是微信支付防篡改的核心机制。V3版本采用RSA-SHA256算法,相比V2的MD5签名更难破解,但实现更复杂。理解签名原理可避免90%的「签名失败」问题。
String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
String nonceStr = WxPayAPI.generateNonceStr();
String bodyJson = JSON.toJSONString(request);
String bodyHash = DigestUtils.sha256Hex(bodyJson);
// 构造待签名字符串
String message = "POST\n/v3/pay/transactions/jsapi\n" + timestamp + "\n" + nonceStr + "\n" + bodyHash + "\n";
// 使用商户私钥签名(RSA/SHA256)
Signature signer = Signature.getInstance("SHA256withRSA");
signer.initSign(privateKey);
signer.update(message.getBytes(StandardCharsets.UTF_8));
String signature = Base64.getEncoder().encodeToString(signer.sign());
// Authorization头
String authorization = "mchid=\"" + mchId + "\",nonce_str=\"" + nonceStr + "\",timestamp=\"" + timestamp + "\",signature=\"" + signature + "\"";
| 错误码 | 现象 | 根本原因 | 解决方案 |
|---|---|---|---|
SIGN_ERROR | 返回401 Unauthorized | 签名值不匹配 | ① 核对私钥是否为最新证书 ② 检查body是否与实际发送内容完全一致(含空格) |
TIMESTAMP_EXPIRED | 返回400 Bad Request | 时间戳超5分钟 | 确保请求前同步服务器时间(使用NTP) |
INVALID_PLATFORM_CERT | 验签失败 | 平台证书未更新 | 定期调用/v3/platform/certificates下载证书并缓存 |
微信支付平台证书(用于验签通知)每90天自动更新。建议:
微信支付结果通知是订单状态的唯一可信来源。前端回调(如wx.requestPayment的success)仅表示用户完成支付动作,但可能因网络问题未真正到账。因此:必须依赖异步通知更新订单状态。
通知为JSON格式,关键字段如下:
{
"id": "通知ID_123456",
"create_time": "2026-04-05T12:30:45+08:00",
"resource": {
"algorithm": "AEAD_AES_256_GCM",
"ciphertext": "加密内容(Base64)",
"nonce": "随机串",
"associated_data": "附加数据"
},
"event_type": "TRANSACTION.SUCCESS",
"summary": "支付成功"
}
其中ciphertext是加密内容,需用APIv3密钥解密:
String cipherText = notification.getResource().getCiphertext();
String associatedData = notification.getResource().getAssociatedData();
String nonce = notification.getResource().getNonce();
AesGcmDecryptUtil decryptUtil = new AesGcmDecryptUtil(apiV3Key);
String plaintext = decryptUtil.decrypt(associatedData, nonce, cipherText);
// plaintext为真实支付结果:
// { "trade_state": "SUCCESS", "transaction_id": "420000123456789", "out_trade_no": "TX1617600000" }
@PostMapping("/api/pay/notify")
public ResponseEntity<String> handlePayNotify(@RequestBody String body, @RequestHeader("Wechatpay-Serial") String serial, @RequestHeader("Wechatpay-Signature") String signature, @RequestHeader("Wechatpay-Timestamp") String timestamp) {
try {
// 1. 验证签名
boolean valid = payService.checkSignature(timestamp, nonceStr, body, signature);
if (!valid) {
log.error("通知验签失败");
return ResponseEntity.status(401).body("fail");
}
// 2. 解密通知内容
PayNotifyResponse notify = payService.decodeNotifyResponse(body);
PayOrder order = notify.getResource();
// 3. 校验订单状态与金额
if (!"SUCCESS".equals(order.getTradeState())) {
log.warn("支付未成功: {}", order.getTradeState());
return ResponseEntity.ok("success");
}
// 4. 更新订单(注意幂等性)
String outTradeNo = order.getOutTradeNo();
PayOrder existing = orderService.findByOutTradeNo(outTradeNo);
if (existing == null || existing.getStatus() == OrderStatus.PAID) {
return ResponseEntity.ok("success"); // 幂等处理
}
orderService.updatePaid(outTradeNo, order.getTransactionId());
// 5. 发送业务通知(如:发货、积分奖励)
orderService.triggerDelivery(outTradeNo);
return ResponseEntity.ok("<xml><return_code>SUCCESS</return_code></xml>");
} catch (Exception e) {
log.error("通知处理异常", e);
return ResponseEntity.status(500).body("fail");
}
}
微信支付通知若未收到200 OK响应,会按以下策略重试:
15s/10m/1h/6h/15h(共5次),总计约37小时。因此:
200 OK(且非JSON格式的XML字符串)success避免无限重试微信支付通知来源IP需严格校验(101.226.240.0/24, 101.226.241.0/24, 101.226.242.0/24)。推荐在Nginx层配置:
location /api/pay/notify {
allow 101.226.240.0/24;
allow 101.226.241.0/24;
allow 101.226.242.0/24;
deny all;
proxy_pass http://backend;
}
退款是支付的逆向流程。微信支付支持:全额退款、部分退款、多次退款,但需注意:退款金额不能超过原订单支付金额。
trade_state=SUCCESS)RefundRequest request = new RefundRequest();
request.setOutTradeNo("TX1617600000");
request.setOutRefundNo("REF" + System.currentTimeMillis()); // 商户退款单号
request.setAmount(new RefundAmount()
.setRefund(50) // 退款金额:50分
.setTotal(100) // 原订单金额:100分
.setCurrency("CNY")
);
try {
RefundResponse refund = payService.refund(request);
log.info("退款成功: {}", refund.getRefundId()); // 微信退款单号
} catch (WxPayException e) {
if ("ORDER_NOT_EXIST".equals(e.getErrorCode())) {
// 订单不存在 → 检查是否已退款
RefundQuery query = payService.queryRefundByOutRefundNo("REF1617600000");
if (query != null && "SUCCESS".equals(query.getRefundStatus())) {
log.warn("订单已退款,跳过");
}
}
}
退款成功后,微信会发送通知:
event_type = "REFUND.SUCCESS"
结构与支付通知类似,需解密后处理:
refund_status = "SUCCESS")| 问题 | 原因 | 解决方案 |
|---|---|---|
NO_AUTH | 商户号未开通退款权限 | 登录商户平台 →「交易中心」→「退款」→ 申请退款权限 |
AMOUNT_LIMIT | 退款金额 > 原订单金额 | 校验refund.total ≤ order.total |
REFUND_TIME_LIMIT | 订单支付超过1年 | 仅允许1年内退款,超期需联系微信客服 |
根据真实开发经验,以下错误码占支付问题的85%以上:
| 错误码 | 说明 | 修复方案 |
|---|---|---|
INVALID_REQUEST | 参数格式错误 | ① 检查openid是否为空 ② amount.total是否为整数 ③ description是否超28字 |
APPID_NOT_BIND | 小程序未绑定商户号 | 登录商户平台 →「产品中心」→「开发配置」→ 绑定小程序AppID |
ORDER_REPEAT | 商户订单号重复 | 确保out_trade_no唯一,推荐:TX + timestamp + random(4) |
NOT_ENOUGH | 商户余额不足 | 检查商户号余额(商户平台→「资金管理」) |
| 错误码 | 说明 | 修复方案 |
|---|---|---|
USER_PAYING | 用户正在支付中(超时重试) | 前端提示“支付中,请稍候”,3秒后重新查询订单 |
ORDER_CLOSED | 订单已关闭 | 检查是否重复调用closeOrder |
ORDER_PAID | 订单已支付 | 检查是否重复提交支付请求 |
| 错误码 | 说明 | 修复方案 |
|---|---|---|
SIGN_ERROR | 通知签名验证失败 | ① 检查平台证书是否最新 ② 验证timestamp与nonce_str是否匹配请求 |
RECEIVER_FAILED | 通知接收失败 | ① 检查服务器防火墙 ② 确保返回200 OK(非JSON) |
GET /v3/pay/transactions/out-trade-no/{out_trade_no}https://api.mch.weixin.qq.com/sandboxnewWxPayApi.setLogHandler((level, msg) -> log.debug("[WXPay] {}", msg));date -s "$(curl -s --head http://www.xservx.com | grep Date: | cut -d' ' -f2-7)"我们整理了近期开发者高频提问,覆盖技术细节、合规、性能等维度:
答:微信支付提供标准API,任何后端语言(Node.js/Python/Go)均可接入。但Java因企业级稳定性高,成为主流选择。我们推荐使用weixin-java-pay开源库,已封装所有签名、验签、通知处理逻辑,大幅降低出错率。
答:关键在幂等性设计:
out_trade_no必须全局唯一(建议:业务前缀+时间戳+用户ID+随机数)答:微信提供沙箱测试账号(mchid: 1900006321),步骤如下:
https://api.mch.weixin.qq.com/sandboxnewwxf8b4f85f3a794e77)openid: oUpF8uMuA2_Mb3V6bI6rQ019N5Ag答:可以!微信支付支持「开票入口」集成。流程:
receipt: { "receipt": true, "accounting_subject": "技术服务费" }wx.chooseInvoice({ ... })打开微信发票收票箱答:严格遵守《个人信息保护法》:
答:手续费由商户承担。微信从退款金额中扣除手续费(费率0.1%),剩余部分退至用户账户。例如:退款100元 → 用户实收99.9元。需在订单页明确告知用户。
答:关键在减少用户流失:
time_out_express设为30分钟答:采用「通知+查询」双保险:
SELECT ... FOR UPDATE防并发答:建议接入Prometheus+Grafana:
整理必备工具与资源,助您高效开发:
out_trade_no(Java/Node.js版)| 项目 | GitHub地址 | 特点 |
|---|---|---|
weixin-java-pay | github.com/WeChat-Group/WxJava | Java最成熟方案,支持V1/V2/V3,文档完善 |
wechatpay-java | github.com/wechatpay-apiv3/wechatpay-java | 官方推荐,专注V3,轻量级 |
wxpay-sdk | github.com/chanjarster/wxpay-sdk | 极简API,适合快速上手 |
weixin-java-pay源码,理解签名逻辑refund_status)