2024最新版：Java集成微信支付APIV3保姆级教程（含完整代码）

2024年Java集成微信支付APIV3全流程实战指南微信支付作为国内移动支付领域的核心基础设施其APIV3版本在安全性、易用性和功能性上都实现了显著提升。本文将带您从零开始全面掌握Java环境下微信支付APIV3的集成方法包含最新技术要点和实战经验。1. 环境准备与基础配置在开始编码前我们需要完成必要的准备工作。首先确保您已经拥有微信支付商户平台账号并完成了基本信息的配置。以下是必须获取的核心参数APPID开发者应用唯一标识MCHID微信支付分配的商户号API密钥32位随机字符串用于签名生成APIv3密钥与v2密钥不同需单独设置商户证书序列号从商户平台下载的证书中包含建议将这些敏感信息存储在环境变量或专业的配置管理服务中而非直接硬编码在项目里。以下是一个典型的Spring Boot配置示例# application.yml配置示例 wxpay: app-id: ${WECHAT_APP_ID} mch-id: ${WECHAT_MCH_ID} api-v3-key: ${WECHAT_API_V3_KEY} key-pem-path: classpath:certs/apiclient_key.pem serial-no: ${WECHAT_SERIAL_NO} base-url: https://api.mch.weixin.qq.com安全提示证书文件应存放在项目resources目录的安全子文件夹中并通过.gitignore排除提交2. 依赖引入与HTTP客户端配置微信支付APIV3官方推荐使用其提供的Java SDK它封装了签名生成、验证等复杂逻辑。在Maven项目中添加以下依赖dependency groupIdcom.github.wechatpay-apiv3/groupId artifactIdwechatpay-apache-httpclient/artifactId version0.4.8/version /dependency接下来配置HTTP客户端这是与微信支付API交互的核心组件。我们需要创建一个Spring配置类Configuration public class WechatPayConfig { Value(${wxpay.key-pem-path}) private String keyPemPath; Bean public CloseableHttpClient wechatPayHttpClient(Verifier verifier) { return WechatPayHttpClientBuilder.create() .withMerchant(mchId, serialNo, getPrivateKey()) .withValidator(new WechatPay2Validator(verifier)) .build(); } private PrivateKey getPrivateKey() { try (InputStream inputStream new ClassPathResource(keyPemPath).getInputStream()) { return PemUtil.loadPrivateKey(inputStream); } catch (IOException e) { throw new RuntimeException(加载商户私钥失败, e); } } }3. 支付功能实现详解3.1 统一下单接口微信支付APIV3支持多种支付场景包括JSAPI、APP、H5、Native等。我们首先实现一个通用的下单接口RestController RequestMapping(/api/payment) public class PaymentController { Autowired private WechatPayService wechatPayService; PostMapping(/create) public ResponseEntityMapString, Object createPayment( RequestBody PaymentRequest request) { MapString, Object result wechatPayService.createPayment(request); return ResponseEntity.ok(result); } }服务层实现核心逻辑Service public class WechatPayServiceImpl implements WechatPayService { private static final MapString, String PAYMENT_TYPE_MAPPING Map.of( JSAPI, /v3/pay/transactions/jsapi, APP, /v3/pay/transactions/app, H5, /v3/pay/transactions/h5, NATIVE, /v3/pay/transactions/native ); Override public MapString, Object createPayment(PaymentRequest request) { String url baseUrl PAYMENT_TYPE_MAPPING.get(request.getType()); MapString, Object params new HashMap(); params.put(appid, appId); params.put(mchid, mchId); params.put(description, request.getDescription()); params.put(out_trade_no, generateOrderNo()); params.put(notify_url, notifyUrl); MapString, Object amount new HashMap(); amount.put(total, request.getAmount()); amount.put(currency, CNY); params.put(amount, amount); // 根据不同支付类型添加特定参数 addSceneInfo(params, request); String response httpClient.execute(url, JSON.toJSONString(params)); return processResponse(response, request.getType()); } private void addSceneInfo(MapString, Object params, PaymentRequest request) { MapString, Object sceneInfo new HashMap(); sceneInfo.put(payer_client_ip, request.getClientIp()); switch (request.getType()) { case H5: sceneInfo.put(h5_info, Map.of(type, Wap)); break; case JSAPI: params.put(payer, Map.of(openid, request.getOpenid())); break; } if (!sceneInfo.isEmpty()) { params.put(scene_info, sceneInfo); } } }3.2 支付结果通知处理微信支付通过异步通知告知支付结果我们需要实现一个安全可靠的接口来处理这些通知RestController RequestMapping(/api/notify) public class PaymentNotifyController { PostMapping(/payment) public MapString, String handlePaymentNotify( HttpServletRequest request, HttpServletResponse response) { try { String body getRequestBody(request); MapString, String headers getRequestHeaders(request); // 验证签名 if (!signatureValidator.validate(headers, body)) { return failureResponse(response); } // 解密通知数据 MapString, Object resource decryptResource(body); String orderNo (String) resource.get(out_trade_no); // 处理业务逻辑 paymentService.handlePaymentSuccess(orderNo, resource); return successResponse(response); } catch (Exception e) { log.error(处理支付通知异常, e); return failureResponse(response); } } private MapString, String successResponse(HttpServletResponse response) { response.setStatus(200); return Map.of(code, SUCCESS, message, 成功); } }4. 进阶功能实现4.1 订单查询与关闭完善的支付系统需要提供订单状态查询和异常订单处理能力Service public class OrderQueryServiceImpl implements OrderQueryService { Override public MapString, Object queryOrder(String orderNo) { String url String.format(%s/v3/pay/transactions/out-trade-no/%s?mchid%s, baseUrl, orderNo, mchId); String response httpClient.executeGet(url); return JSON.parseObject(response, new TypeReferenceMapString, Object() {}); } Override public void closeOrder(String orderNo) { String url String.format(%s/v3/pay/transactions/out-trade-no/%s/close, baseUrl, orderNo); MapString, String params Map.of(mchid, mchId); httpClient.executePost(url, JSON.toJSONString(params)); } }4.2 退款功能实现退款是支付系统的重要组成部分APIV3提供了完整的退款接口Service public class RefundServiceImpl implements RefundService { Override public String createRefund(RefundRequest request) { String url baseUrl /v3/refund/domestic/refunds; MapString, Object params new HashMap(); params.put(out_trade_no, request.getOrderNo()); params.put(out_refund_no, generateRefundNo()); params.put(reason, request.getReason()); params.put(notify_url, refundNotifyUrl); MapString, Object amount new HashMap(); amount.put(refund, request.getRefundAmount()); amount.put(total, request.getTotalAmount()); amount.put(currency, CNY); params.put(amount, amount); String response httpClient.executePost(url, JSON.toJSONString(params)); return JSON.parseObject(response).getString(refund_id); } Override public MapString, Object queryRefund(String refundNo) { String url baseUrl /v3/refund/domestic/refunds/ refundNo; String response httpClient.executeGet(url); return JSON.parseObject(response, new TypeReferenceMapString, Object() {}); } }5. 安全最佳实践微信支付涉及资金流转安全性至关重要。以下是几个关键的安全实践证书管理定期轮换API证书建议每3个月使用密码保护证书文件不同环境使用不同证书敏感信息保护// 错误示例 - 硬编码敏感信息 String apiKey abcdef1234567890; // 正确做法 - 从安全存储获取 String apiKey securityService.getSecret(wechat-api-key);请求验证验证通知签名检查时间戳防止重放攻击实现幂等性处理日志记录记录关键操作脱敏处理敏感数据设置适当的日志保留策略在实际项目中我们曾遇到因证书过期导致的支付失败问题。通过实现证书自动更新机制我们创建了一个定时任务检查证书有效期并在到期前自动从微信支付平台获取新证书彻底解决了这个问题。