微信小程序支付 Java

微信小程序支付 Java 开发实战指南

从零构建稳定可靠的微信支付能力|覆盖小程序V3 API全流程|含完整Java代码示例|安全合规|实战避坑

立即开始接入

一、微信小程序支付接入全流程详解

接入微信小程序支付并非简单调用几个API,而是一套严谨的业务与安全体系。开发者需依次完成以下关键环节:

1.1 资质准备与配置

  • ① 企业资质:需提供有效的营业执照、ICP备案号、微信小程序支付商户号(由微信支付官方审核发放)
  • ② 小程序绑定:在微信公众平台「开发管理」→「开发设置」中绑定商户号(注意:必须为服务号或认证小程序)
  • ③ 支付权限开通:登录pay.weixin.qq.com商户平台 →「产品中心」→「开发配置」→ 开通「小程序」支付能力
  • ④ 配置回调地址:在商户平台设置「支付结果通知」与「退款结果通知」的URL(必须为公网可访问的HTTPS地址)

1.2 开发前准备

  • ① 获取「APIv3密钥」:商户平台 →「API安全」→ 下载API密钥(32位字符串)并妥善保管
  • ② 申请「APIv3证书」:在商户平台上传平台证书后,下载APIv3证书(.pem格式),用于加签与验签
  • ③ 配置SDK依赖(推荐使用weixin-java-pay):
<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>weixin-java-pay</artifactId>
  <version>4.5.0</version>
</dependency>

1.3 核心流程图解

  1. 用户在小程序内点击「支付」按钮
  2. 小程序前端调用 wx.requestPayment 前,需先向后端(Java服务)发起「统一下单」请求
  3. Java后端调用微信支付V3 API:POST /v3/pay/transactions/jsapi,传入:
    • appid、mchid(商户号)
    • description(商品描述,如:「XServX小程序订单-123456」)
    • out_trade_no(商户订单号,唯一)
    • amount.total(订单总金额,单位:分)
    • payer.openid(用户在小程序的唯一标识)
    • notify_url(异步通知地址)
  4. 微信服务器返回:prepay_id(预支付交易会话标识)
  5. Java后端构造签名参数(含:appId、timeStamp、nonceStr、package、signType、paySign)并返回给前端
  6. 小程序前端调用 wx.requestPayment({...}) 发起支付
  7. 用户完成支付后,微信服务器异步通知Java后端(POST到notify_url)
  8. 后端验证签名 → 处理订单逻辑(如:更新订单状态、发货、发送通知)→ 返回<xml><return_code>SUCCESS</return_code></xml>

1.4 典型Java后端代码示例(统一下单)

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()));
}

1.5 小程序前端调用示例(JavaScript)

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深度解析(Java实现)

微信支付V3 API是基于HTTPS+JSON的RESTful接口,采用RFC 7517标准的JWT签名机制,彻底取代旧版V2的MD5/SHA1签名体系。其核心优势在于:更强的安全性、更清晰的资源层次、更规范的错误码体系。

2.1 关键V3接口清单

接口名称路径用途Java SDK方法
统一下单(JSAPI)/v3/pay/transactions/jsapi创建订单,获取prepay_idjsapi(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)

2.2 请求头规范详解

所有V3请求必须携带以下Header(由SDK自动处理,但理解原理至关重要):

  • Authorization: Bearer mchid_xxx:timestamp_xxx:nonce_xxx:signature_xxx
  • Accept: application/json
  • Content-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)

2.3 异常处理规范(Java)

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)等
}

2.4 安全加固建议

  • ① 所有请求必须校验来源IP(仅允许微信服务器IP段,如:101.226.240.0/24)
  • ② 验证签名:收到通知时,必须使用WxPayService.checkNotification()验签,禁止直接信任客户端数据
  • ③ 幂等性设计:退款/关闭订单等操作需传入idempotency_key防止重复提交
  • ④ 密钥管理:私钥、APIv3密钥严禁硬编码,应通过环境变量或密钥管理服务(如Vault)注入

三、签名机制:安全通信的基石

签名是微信支付防篡改的核心机制。V3版本采用RSA-SHA256算法,相比V2的MD5签名更难破解,但实现更复杂。理解签名原理可避免90%的「签名失败」问题。

3.1 签名生成四要素

  1. 请求时间戳(timestamp):当前Unix时间戳(秒),有效期5分钟
  2. 随机字符串(nonce_str):32位以内字母数字组合(可用UUID简化)
  3. 请求报文主体(body):JSON字符串(如统一下单请求体),需先计算SHA256摘要
  4. 商户私钥(private_key):商户在平台下载的APIv3证书对应的私钥(PKCS#8格式)

3.2 签名生成流程(Java伪代码)

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 + "\"";

3.3 常见签名错误排查

错误码现象根本原因解决方案
SIGN_ERROR返回401 Unauthorized签名值不匹配① 核对私钥是否为最新证书 ② 检查body是否与实际发送内容完全一致(含空格)
TIMESTAMP_EXPIRED返回400 Bad Request时间戳超5分钟确保请求前同步服务器时间(使用NTP)
INVALID_PLATFORM_CERT验签失败平台证书未更新定期调用/v3/platform/certificates下载证书并缓存

3.4 平台证书管理最佳实践

微信支付平台证书(用于验签通知)每90天自动更新。建议:

  • ① 启动时自动下载并缓存证书(存入Redis或本地文件)
  • ② 设置定时任务(每日凌晨2点)更新证书
  • ③ 验签时优先使用缓存证书,失败则重新下载

四、异步通知处理:订单状态的最终依据

微信支付结果通知是订单状态的唯一可信来源。前端回调(如wx.requestPayment的success)仅表示用户完成支付动作,但可能因网络问题未真正到账。因此:必须依赖异步通知更新订单状态。

4.1 通知内容结构

通知为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" }

4.2 Java后端处理逻辑

@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");
  }
}

4.3 通知重试机制

微信支付通知若未收到200 OK响应,会按以下策略重试:
15s/10m/1h/6h/15h(共5次),总计约37小时。因此:

  • ① 必须返回200 OK(且非JSON格式的XML字符串)
  • ② 业务处理失败时,也应返回success避免无限重试
  • ③ 用数据库事务保证订单状态更新的原子性

4.4 安全加固:IP白名单

微信支付通知来源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;
}

五、退款流程:从申请到资金原路退回

退款是支付的逆向流程。微信支付支持:全额退款、部分退款、多次退款,但需注意:退款金额不能超过原订单支付金额。

5.1 退款必要条件

  • ① 订单已支付成功(trade_state=SUCCESS)
  • ② 订单未关闭(关闭后不可退款)
  • ③ 退款申请在订单支付后1年内
  • ④ 商户号已开通退款权限(需在商户平台申请)

5.2 Java退款请求示例

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("订单已退款,跳过");
    }
  }
}

5.3 退款结果通知

退款成功后,微信会发送通知:
event_type = "REFUND.SUCCESS"
结构与支付通知类似,需解密后处理:

  • ① 更新退款状态(refund_status = "SUCCESS")
  • ② 记录退款时间、手续费、退款到银行账户时间
  • ③ 触发售后流程(如:生成退货地址)

5.4 常见退款问题

问题原因解决方案
NO_AUTH商户号未开通退款权限登录商户平台 →「交易中心」→「退款」→ 申请退款权限
AMOUNT_LIMIT退款金额 > 原订单金额校验refund.total ≤ order.total
REFUND_TIME_LIMIT订单支付超过1年仅允许1年内退款,超期需联系微信客服

六、高频错误码排查手册(Java开发者必藏)

根据真实开发经验,以下错误码占支付问题的85%以上:

6.1 统一下单阶段

错误码说明修复方案
INVALID_REQUEST参数格式错误① 检查openid是否为空 ② amount.total是否为整数 ③ description是否超28字
APPID_NOT_BIND小程序未绑定商户号登录商户平台 →「产品中心」→「开发配置」→ 绑定小程序AppID
ORDER_REPEAT商户订单号重复确保out_trade_no唯一,推荐:TX + timestamp + random(4)
NOT_ENOUGH商户余额不足检查商户号余额(商户平台→「资金管理」)

6.2 支付阶段

错误码说明修复方案
USER_PAYING用户正在支付中(超时重试)前端提示“支付中,请稍候”,3秒后重新查询订单
ORDER_CLOSED订单已关闭检查是否重复调用closeOrder
ORDER_PAID订单已支付检查是否重复提交支付请求

6.3 回调阶段

错误码说明修复方案
SIGN_ERROR通知签名验证失败① 检查平台证书是否最新 ② 验证timestamp与nonce_str是否匹配请求
RECEIVER_FAILED通知接收失败① 检查服务器防火墙 ② 确保返回200 OK(非JSON)

6.4 调试技巧

  • ① 使用微信官方「支付结果查询」接口:GET /v3/pay/transactions/out-trade-no/{out_trade_no}
  • ② 在测试环境使用沙箱:https://api.mch.weixin.qq.com/sandboxnew
  • ③ 开启SDK日志:WxPayApi.setLogHandler((level, msg) -> log.debug("[WXPay] {}", msg));
  • ④ 检查时间同步:date -s "$(curl -s --head http://www.xservx.com | grep Date: | cut -d' ' -f2-7)"

七、网友最关心的问题汇总

我们整理了近期开发者高频提问,覆盖技术细节、合规、性能等维度:

接入流程
安全合规
性能优化

Q1:小程序支付必须用Java吗?其他语言能用吗?

答:微信支付提供标准API,任何后端语言(Node.js/Python/Go)均可接入。但Java因企业级稳定性高,成为主流选择。我们推荐使用weixin-java-pay开源库,已封装所有签名、验签、通知处理逻辑,大幅降低出错率。

Q2:如何避免订单重复支付?

答:关键在幂等性设计:

  • ① 商户订单号out_trade_no必须全局唯一(建议:业务前缀+时间戳+用户ID+随机数)
  • ② 支付前先查询订单状态,若已支付则直接返回成功
  • ③ 支付回调中,更新订单前检查状态,防止重复处理

Q3:沙箱环境怎么用?

答:微信提供沙箱测试账号(mchid: 1900006321),步骤如下:

  1. 登录商户平台 →「APIv3密钥」→ 下载沙箱证书
  2. 替换生产环境配置为沙箱地址:https://api.mch.weixin.qq.com/sandboxnew
  3. 使用沙箱专用测试小程序(AppID: wxf8b4f85f3a794e77)
  4. 测试账号:openid: oUpF8uMuA2_Mb3V6bI6rQ019N5Ag

Q4:用户支付后能开发票吗?

答:可以!微信支付支持「开票入口」集成。流程:

  1. 在统一下单时传入:receipt: { "receipt": true, "accounting_subject": "技术服务费" }
  2. 用户支付后,在小程序内调用:wx.chooseInvoice({ ... })打开微信发票收票箱
  3. 用户可选择发票抬头并开具电子发票

Q5:如何合规处理用户隐私数据?

答:严格遵守《个人信息保护法》:

  • ① 仅收集必要信息(订单号、openid、金额)
  • ② openid不得用于其他业务(如营销推送)
  • ③ 支付数据加密存储,敏感字段脱敏
  • ④ 定期删除过期订单数据(建议保留6个月)

Q6:退款手续费谁承担?

答:手续费由商户承担。微信从退款金额中扣除手续费(费率0.1%),剩余部分退至用户账户。例如:退款100元 → 用户实收99.9元。需在订单页明确告知用户。

Q7:如何提升支付成功率?

答:关键在减少用户流失:

  • ① 优化前端交互:支付按钮置于底部,避免误触
  • ② 支付超时自动延长:time_out_express设为30分钟
  • ③ 支付失败时提供替代方案(如:转账到零钱)
  • ④ 对高价值订单,发送微信模板消息提醒

Q8:高并发下如何保证通知不丢失?

答:采用「通知+查询」双保险:

  1. 异步通知处理:快速响应,用消息队列(如RabbitMQ)解耦业务逻辑
  2. 主动查询兜底:对未收到通知的订单,定时任务查询订单状态(如:每5分钟查超时10分钟未支付订单)
  3. 数据库加锁:更新订单时使用SELECT ... FOR UPDATE防并发

Q9:如何监控支付系统健康度?

答:建议接入Prometheus+Grafana:

  • 监控指标:
    • 统一下单成功率
    • 通知接收延迟
    • 退款成功率
    • API调用QPS
  • 告警规则:
    • 支付失败率 > 5% → 短信告警
    • 通知延迟 > 30秒 → 邮件告警

八、开发者工具箱:效率倍增器

整理必备工具与资源,助您高效开发:

8.1 必备工具

  • ① 微信支付APIv3签名工具(Chrome扩展):一键生成签名参数,调试用
  • ② Postman预设集合:导入微信支付V3接口模板(含自动签名)
  • ③ 订单号生成器:在线生成唯一out_trade_no(Java/Node.js版)
  • ④ 微信支付沙箱测试号申请:[https://payapp.weixin.qq.com/appmch/home](https://payapp.weixin.qq.com/appmch/home)

8.2 开源库推荐

项目GitHub地址特点
weixin-java-paygithub.com/WeChat-Group/WxJavaJava最成熟方案,支持V1/V2/V3,文档完善
wechatpay-javagithub.com/wechatpay-apiv3/wechatpay-java官方推荐,专注V3,轻量级
wxpay-sdkgithub.com/chanjarster/wxpay-sdk极简API,适合快速上手

8.3 学习路径建议

  1. ① 阅读官方文档:https://pay.weixin.qq.com/wiki/doc/apiv3/wxpay/
  2. ② 搭建沙箱环境,完成「下单→支付→查询」全流程
  3. ③ 阅读weixin-java-pay源码,理解签名逻辑
  4. ④ 参与开源社区(微信支付技术交流群/QQ群)
  5. ⑤ 实战:开发一个完整电商小程序(含订单、支付、退款)

8.4 常见问题速查表

Q:支付后订单未更新?
A:① 检查通知URL是否公网可访问 ② 查看微信支付商户平台「通知记录」 ③ 检查服务器日志
Q:退款失败?
A:① 确认订单未关闭 ② 核对退款金额 ③ 检查商户余额 ④ 查看退款失败原因(refund_status)
Q:如何测试大额支付?
A:沙箱支持最大金额1000元;生产环境需真实支付,不可测试大额