简介面向Java开发者的支付宝扫码支付集成项目完整覆盖从SDK接入、二维码生成、支付请求发起到结果回调的完整链路适合在电商、O2O等场景中需要快速接入支付功能、解决集成中常见问题的工程师参考。资源压缩包共含124个文件包括37个jar依赖库、23个Java源码文件、12个xml配置、9个properties参数文件以及前端展示所需的html、js、css等整体大小27.64MB目录结构清晰便于按模块查阅。目前已有2483人学习浏览社区认可度较高。核心示例代码涉及AlipayFaceToFaceController、ZFBFaceToFaceModel等类可直观了解如何配置zfbinfo.properties中的appid与密钥、与支付宝服务器进行API交互、处理异步回调并同步订单状态同时涵盖支付安全加固、异常场景测试与调试等实践要点并附有支付宝刷脸支付官方奖励政策信息便于同步关注政策动态。适合有一定Java基础、希望系统掌握扫码支付集成与回调机制的开发者深入参考。1. 扫码支付项目拿到的第一手资产当面付链路到底能跑什么不少Java后端第一次接触支付宝扫码支付都栽在同一个地方开放平台给了你当面付的示例包下载下来却发现核心代码全是编译好的class文件demo能跑通想改业务逻辑却像在拆黑匣子。这套以AlipayFaceToFace、ZFBFaceToFaceModel为核心的Java集成支付宝扫码支付项目就是典型的当面付工程——它把下单、生成二维码、回调验签整条主链路串好了刷脸支付和扫码支付在接口层面共用同一套SDK指令当年很多开发者就是靠拆这类工程才搞明白支付集成是怎么回事。它适合正在给电商后台或线下门店接扫码收银的Java从业者也适合想弄懂回调怎么验签、怎么防伪造的进阶学习者。这里要提前说清楚奖励政策属于平台运营侧的规则代码里并没有独立实现你拿到手的核心价值在支付主链路本身。2. 先把配置这扇门推开zfbinfo.properties 里的私钥、公钥和网关怎么填2.1 为什么支付集成的第一步永远是配置初始化支付和普通HTTP接口调用有一个本质区别每一次请求都要带签名服务端要验签名。签名用的应用私钥保存在本地验签用的支付宝公钥从开放平台获取这两把钥匙配错了后面所有接口调用全是死路。项目里的zfbinfo.properties就是干这个的它把appid、私钥、公钥、回调地址集中放在一个文件里方便在不同环境之间切换。很多新手跳过这一步直接跑demo结果一遍遍报“验签失败”原因往往只是配置文件的某个值填错了。这个文件的名字也提示了它的定位zfbinfo就是“支付宝信息”的缩写它服务的是整个FaceToFace支付模块的初始化。在动手写业务代码之前先把配置文件里每一个键的含义和来源搞明白比急着调接口更重要。2.2 zfbinfo.properties 参数全解一个典型的zfbinfo.properties包含了下面这些键。不同的项目可能命名略有差异但核心参数不会超出这个范围参数名示例值说明从哪拿appid2021000123456789应用唯一标识开放平台控制台应用详情页private_keyMIIEvQIBADANBgkqhkiG9w0B...应用私钥PKCS8格式密钥生成工具生成保存在本地alipay_public_keyMIIBIjANBgkqhkiG9w0BAQEF...支付宝公钥用于验签开放平台上传应用公钥后获取notify_urlhttps://api.example.com/alipay/notify异步回调地址自己业务系统的接口地址gatewayhttps://openapi.alipay.com/gateway.do网关地址正式环境固定值sign_typeRSA2签名算法固定RSA2对应SHA256withRSAcharsetUTF-8编码固定UTF-8formatjson请求报文格式固定json这里最容易搞混的是alipay_public_key。它是支付宝的公钥不是你自己生成的“应用公钥”。流程是用密钥工具生成一对RSA2密钥——应用私钥留本地应用公钥上传到开放平台平台再返回一个支付宝公钥给你。配置里填的是平台返回的那个支付宝公钥。2.3 初始化 AlipayClient代码怎么写参数为什么不能写死读取配置文件的代码不难但有两个细节值得注意。第一Properties默认按ISO-8859-1编码读取文件文件里的中文注释会变成乱码虽然不影响参数读取但最好用UTF-8显式指定编码。第二私钥值可能包含换行符从properties里读出来时换行符会被转义需要做一次处理不过官方SDK内部会处理标准格式的私钥文本配置时保持原样即可。public class ZFBFaceToFaceConfig { private static final Properties PROPS new Properties(); static { try (InputStream in ZFBFaceToFaceConfig.class .getClassLoader().getResourceAsStream(zfbinfo.properties)) { if (in null) { throw new RuntimeException(zfbinfo.properties 未找到请检查 resources 目录); } // 用 UTF-8 读取避免中文注释乱码 PROPS.load(new InputStreamReader(in, StandardCharsets.UTF_8)); } catch (IOException e) { throw new RuntimeException(支付宝配置文件加载失败, e); } } public static String get(String key) { String value PROPS.getProperty(key); if (value null || value.trim().isEmpty()) { throw new RuntimeException(配置项缺失: key); } return value.trim(); } }这段静态代码块在类加载时执行一次把配置文件读进内存。trim()很重要从properties读取的值可能带首尾空格不处理会在拼接签名串时出幺蛾子。加载完成后初始化支付宝客户端AlipayClient alipayClient new DefaultAlipayClient( ZFBFaceToFaceConfig.get(gateway), ZFBFaceToFaceConfig.get(appid), ZFBFaceToFaceConfig.get(private_key), ZFBFaceToFaceConfig.get(format), ZFBFaceToFaceConfig.get(charset), ZFBFaceToFaceConfig.get(alipay_public_key), ZFBFaceToFaceConfig.get(sign_type) );构造函数的七个参数顺序不能乱网关、APPID、应用私钥、请求格式、编码、支付宝公钥、签名类型。其中网关决定了你走的是正式环境还是沙箱环境沙箱网关是openapi.alipaydev.com二者前缀不同切换环境时最容易犯的错就是忘了改网关。初始化之后这个客户端就是整个支付模块的入口所有交易请求都通过它执行。2.4 密钥生成与格式验证密钥这一关我第一次做的时候也绕了圈子。当时拿密钥工具生成了密钥对把公钥上传到开放平台然后把“应用公钥”填进了alipay_public_key结果下单接口一直报验签失败。后面才反应过来配置里要的是平台返回的支付宝公钥不是自己手头那个应用公钥。推荐的做法是下载支付宝开放平台官方密钥工具选择RSA2算法生成密钥对。工具会展示应用公钥和应用私钥应用私钥保存到本地Java项目用PKCS8格式的私钥文本。然后把应用公钥复制到开放平台对应应用的“接口加签方式”里保存后平台会生成支付宝公钥这个值才是配置文件里要填的。如果用的是证书模式新创建的应用默认推荐证书模式那DefaultAlipayClient的构造函数又不一样后面避坑章节会专门说。3. 扫码支付主链路precreate 下单、二维码渲染与状态兜底3.1 为什么扫码支付选 alipay.trade.precreate“扫码支付”在支付宝体系里对应的专业名词是“当面付”核心接口是alipay.trade.precreate中文叫“统一收单线下交易预创建”。这个接口的语义是商户主动创建一个交易支付宝返回一个二维码串用户拿支付宝App扫这个码完成付款。它的特点是用户不需要跳转到任何H5页面所有交互都在线下完成非常适合收银台、自助机、POS机这些场景。对比一下其他接口就清楚了alipay.trade.page.pay是电脑网站支付要跳转收银台页面alipay.trade.wap.pay是手机网站支付专为手机浏览器设计。而扫码支付选precreate是因为它把“支付入口”和“支付完成”完全解耦——先拿码后付款适合线下设备长时间等待用户扫码的场景。项目里的AlipayFaceToFace类封装的就是这套逻辑从命名也能看出来刷脸支付和扫码支付共用的是同一个FaceToFace指令体系。3.2 下单代码请求参数怎么组响应怎么拿precreate接口的调用过程分三步组装请求对象、设置业务参数、执行调用并解析二维码。难点在bizContent的JSON结构字段多且都是字符串类型拼的时候容易漏引号。// 1. 组装业务参数注意 total_amount 是字符串单位是元 String bizContent {\out_trade_no\:\ orderNo \,\total_amount\:\ amount \,\subject\:\ subject \,\store_id\:\STORE_001 \,\timeout_express\:\5m\}; AlipayTradePrecreateRequest request new AlipayTradePrecreateRequest(); request.setNotifyUrl(notifyUrl); // 异步回调地址 request.setBizContent(bizContent); try { // 2. 执行请求SDK 内部会完成签名、发送、解析响应 AlipayTradePrecreateResponse response alipayClient.execute(request); if (response.isSuccess()) { String qrCode response.getQrCode(); // 3. qrCode 是字符串需要再转成二维码图片供用户扫描 log.info(下单成功, orderNo{}, qrCodeLength{}, orderNo, qrCode.length()); } else { log.error(下单失败, code{}, subCode{}, msg{}, subMsg{}, response.getCode(), response.getSubCode(), response.getMsg(), response.getSubMsg()); } } catch (AlipayApiException e) { log.error(下单异常, e); }参数里out_trade_no是商家订单号在商户系统内必须唯一支付宝靠它做幂等。total_amount是字符串不是数字单位是元保留两位小数比如9.90。subject是商品标题会在用户的支付宝账单里展示。timeout_express是交易超时时间5m表示5分钟用户超过这个时间未付款交易会自动关闭。响应里最重要的字段是getQrCode()它返回的是一个字符串链接不是二维码图片本身。把这个链接编码成二维码图片后用户扫码手机会自动打开支付页面。失败时sub_code比code更有排查价值它精确指出了业务层面的错误原因比如INVALID_PARAMETER说明参数格式有问题。3.3 把 qr_code 渲染成二维码图片拿到qrCode字符串之后最常用的做法是用Google的zxing库渲染成图片输出到HTTP响应流里前端页面用img标签直接访问这个接口就能看到二维码。当然也可以在后端把图片转成Base64返回给前端两种方式本质上一样。GetMapping(value /qrcode/{orderNo}, produces image/png) public void qrcode(PathVariable String orderNo, HttpServletResponse response) throws Exception { String qrCode orderQrCodeCache.get(orderNo); // 从缓存取出下单时返回的 qrCode QRCodeWriter writer new QRCodeWriter(); // 300x300 像素携带 UTF-8 字符集避免内容编码问题 BitMatrix matrix writer.encode(qrCode, BarcodeFormat.QR_CODE, 300, 300, Map.of(EncodeHintType.CHARACTER_SET, UTF-8)); BufferedImage image MatrixToImageWriter.toBufferedImage(matrix); response.setContentType(image/png); ImageIO.write(image, png, response.getOutputStream()); }下单接口返回qrCode之后要么存数据库要么放缓存二维码接口再根据订单号取出来渲染。注意writer.encode的最后一个参数如果不指定字符集遇到链接里带中文参数的时候可能生成乱码二维码导致用户扫码打不开支付页。另外二维码图片不要每次请求都重新生成同一个订单的qrCode在有效期内是固定不变的缓存起来还能减少重复计算。3.4 支付结果怎么感知回调优先轮询兜底下单成功、二维码渲染出来之后下一个问题是怎么知道用户到底付没付这里有两条路。第一条路是等支付宝的异步回调。用户付款成功后支付宝会向下单时设置的notify_url发起一个POST请求把交易结果推给商户系统。这是最可靠的方式下一章专门讲。第二条路是主动查询调用alipay.trade.query接口问支付宝订单状态作为兜底手段——比如回调因为网络问题延迟了几个小时系统里的订单还挂着“待支付”这时候可以用一个定时任务把超时未支付的订单捞出来主动查一遍。AlipayTradeQueryRequest queryRequest new AlipayTradeQueryRequest(); queryRequest.setBizContent({\out_trade_no\:\ orderNo \}); AlipayTradeQueryResponse queryResponse alipayClient.execute(queryRequest); if (queryResponse.isSuccess() TRADE_SUCCESS.equals(queryResponse.getTradeStatus())) { // TRADE_SUCCESS 表示已支付成功这里再走一遍订单更新逻辑 updateOrderPaid(orderNo, queryResponse.getTradeNo(), queryResponse.getTotalAmount()); }trade.query返回的字段和回调通知几乎一致trade_status同样有WAIT_BUYER_PAY、TRADE_SUCCESS、TRADE_CLOSED几个值。轮询间隔建议10秒一次最多查30次别做成while(true)无限循环。实际项目里我更习惯把回调作为主逻辑查询只用来处理“回调丢了”的异常场景两套逻辑共用同一个订单更新方法保证结果一致。4. 回调处理与资金安全验签规则、幂等更新和返回值讲究4.1 回调通知长什么样用户在手机上输密码、付款成功支付宝服务器会往notify_url发一个表单格式的POST请求。这个请求的参数来自支付宝服务器而不是用户浏览器所以理论上它是可信的——前提是你验签。参数里比较重要的有out_trade_no商户订单号、trade_no支付宝交易号、trade_status交易状态、total_amount实付金额、buyer_id买家支付宝ID、app_id哪个应用创建的交易、sign签名。所有值都是字符串sign用来验签sign_type标注签名算法。这里要强调一个认知请求虽然来自支付宝服务器但网络传输过程中可能被截获、篡改甚至有人在沙箱环境抓包后伪造同样的请求打到你的回调接口。所以回调处理的第一件事永远是验签而不是读参数。4.2 验签是回调处理的第一道闸门支付宝SDK提供了现成的验签方法核心是AlipaySignature.rsaCheckV1。它会把收到的参数按照支付宝的规则排序、拼接、用支付宝公钥验证签名。验签失败直接返回failure让支付宝知道这次通知没处理成功它会稍后重试。PostMapping(/alipay/notify) public String alipayNotify(HttpServletRequest request) { MapString, String params new HashMap(); MapString, String[] requestParams request.getParameterMap(); for (String name : requestParams.keySet()) { params.put(name, String.join(,, requestParams.get(name))); } // 第一步永远是验签验签不通过直接拒绝 boolean signVerified; try { signVerified AlipaySignature.rsaCheckV1( params, ZFBFaceToFaceConfig.get(alipay_public_key), ZFBFaceToFaceConfig.get(charset), ZFBFaceToFaceConfig.get(sign_type)); } catch (AlipayApiException e) { log.error(回调验签异常, e); return failure; } if (!signVerified) { log.warn(回调验签失败, params{}, params); return failure; } // 验签通过处理业务逻辑 handleNotify(params); return success; }验签方法内部会剔除sign和sign_type两个参数再把剩余参数按字典序拼接、加签比对。这里容易踩的坑是把alipay_public_key传成了应用公钥导致验签永远失败。另外三目运算符入参顺序我特意写成了params, 公钥, charset, signType四个参数的顺序不能错写反了SDK不会报参数错误但验签结果永远是false。4.3 业务更新与幂等别让一笔订单被回调两次验签通过之后接下来处理业务更新订单状态、同步库存、给用户发通知。但这里有个容易被忽略的点——支付宝投递回调是“直到商户返回success为止”也就是说如果网络抖动导致商户的响应没送达支付宝会重发通知。如果第一笔通知已经更新了订单第二笔通知再来就会导致重复操作。解决思路很简单更新订单的SQL加上状态条件。private void handleNotify(MapString, String params) { String outTradeNo params.get(out_trade_no); String tradeNo params.get(trade_no); String tradeStatus params.get(trade_status); String totalAmount params.get(total_amount); // 只有 TRADE_SUCCESS 才进入已支付处理 if (!TRADE_SUCCESS.equals(tradeStatus)) { log.info(订单 {} 当前状态 {}, 不做支付处理, outTradeNo, tradeStatus); return; } // 用状态条件保证幂等只有 UNPAID 状态的订单才能被更新为 PAID int rows orderMapper.markPaid(outTradeNo, tradeNo, totalAmount); if (rows 0) { log.warn(订单 {} 已被处理或不存在跳过重复回调, outTradeNo); return; } // 到这里才算支付成功后续做发券、通知等操作 afterPaid(outTradeNo); }markPaid对应的SQL大致是UPDATE orders SET statusPAID, alipay_trade_no#{tradeNo}, paid_amount#{amount} WHERE out_trade_no#{outTradeNo} AND statusUNPAID。这条语句靠statusUNPAID条件保证幂等第一次执行更新一行第二次执行影响行数为0自然就跳过了重复逻辑。比先查再改省了一次查询也避免了并发窗口。4.4 返回值是“success”不是“SUCCESS”这可能是全流程里最反直觉的一个坑。支付宝文档明确要求商户处理成功必须输出纯文本success不能有HTML标签不能有前后空格不能是true更不能是SUCCESS。因为支付宝对响应内容有严格的字符串匹配只要不是success它就认为通知失败会继续重发。重发机制一般是4分钟后重发之后逐步拉长间隔最多24小时内发若干次。我见过一个项目把回调返回值写成了ok结果支付宝一直在重发数据库里堆积了大量重复通知日志订单状态倒是没事幂等保护了但日志量把磁盘打满了。另外注意验签失败时返回failure也不要写成falsefailure会让支付宝停止重发false同理不匹配会引发无意义的频繁重试。简单说成功回success失败回failure外界任何影响判断的东西都不要加。5. 避坑五个高频问题现象、原因、对策5.1 验签失败公钥填成了应用公钥现象调用下单接口或者处理回调时报sign check fail: check Sign and Data Fail!。原因配置里的alipay_public_key填成了自己生成的“应用公钥”而不是开放平台返回的“支付宝公钥”。两者都是base64的一大串字符肉眼几乎分辨不出区别。解决登录开放平台控制台进入应用详情开发设置 → 接口加签方式找到“支付宝公钥”的完整文本复制后整体替换配置值。注意复制时确认头和尾完整不要漏掉字符。凡是用DefaultAlipayClient初始化的项目验签用的都是这个值。5.2 沙箱支付成功但本地回调收不到现象用沙箱应用的支付宝账号扫码付款成功本地服务的/alipay/notify接口迟迟收不到通知。原因沙箱环境和正式环境一样回调是支付宝服务器发起的。本地开发环境跑在localhost或者内网IP支付宝服务器根本访问不到这个地址通知自然发不出来。解决联调期不要用本机地址用内网映射工具比如ngrok把本地端口映射成一个公网HTTPS地址把该地址配到沙箱应用的notify_url上。另一个备选方案是不依赖真实支付用模拟请求直接调用本地回调接口验证业务逻辑后再去真实环境。无论哪种方式都要记得沙箱应用的网关是openapi.alipaydev.com不是正式网关。5.3 金额精度翻车对不上账现象订单金额明明输入的是9.9下单时变成了9.90还能接受但有时候会变成9.900000000000001这种浮点垃圾值回调里金额对不上订单无法匹配。原因业务代码里用了double或Float类型参与金额计算和拼接。浮点数在二进制里本身就不精确运算次数一多误差就出来了。支付宝接口要求金额用字符串传精度最多两位小数浮点数转字符串很容易踩坑。解决Java侧金额统一用BigDecimal传输时用setScale(2, RoundingMode.HALF_UP).toString()转成字符串数据库金额字段用DECIMAL(10,2)不要用float或double前端展示格式化和后端计算分离不要相信前端传来的金额下单金额以服务端计算为准。5.4 拿到手的class文件是黑匣子能跑但不能改现象项目里AlipayFaceToFace.class、ZFBFaceToFaceModel.class这些类能正常编译运行但想加个需求比如在回调里多更新一个字段根本无处下手反编译出来的代码又不敢直接改。原因资源包里放的是编译产物不是源代码。官方示例包经常干这种事把核心逻辑编译好防止被随意改动但对二次开发很不友好。解决我的习惯是用javap -c反编译看核心类调用了SDK的哪些方法、走了哪些分支理清楚链路之后再从零重写自己的业务层。支付宝的接口契约是公开的precreate、trade.query、回调验签这几个核心方法都有官方文档和SDK支撑自己写一遍比逆着class改要快得多。第三方依赖统一从Maven仓库引入alipay-sdk-java不要继续依赖class文件里的老版本SDK。5.5 证书模式和公钥模式混用新应用默认推荐证书现象新创建的应用开放平台默认推荐“证书模式”而非“公钥模式”。如果用新应用跑老项目的DefaultAlipayClient代码会报签名配置不匹配或者响应提示应用未配置对应加签方式。原因证书模式需要应用公钥证书、应用私钥、支付宝公钥证书三个文件初始化方式和公钥模式完全不同。老项目大多基于公钥模式写的两者混用必然出问题。解决最简单的做法是在开放平台把加签方式切换为“公钥模式”上传应用公钥拿到支付宝公钥把代码保持DefaultAlipayClient不变即可。如果你确实要用证书模式初始化要改成CertAlipayRequest代码改动量不小二选一不要两边都掺和。6. 进阶把沙箱支付流程沉淀成自己的测试资产支付开发有个特点功能链路长环境切换成本高每次真实支付都要真金白银。所以把沙箱环境用透等于给自己攒了一套可重复执行的测试资产。我的做法是把全流程拆成三个独立验证节点下单拿码、扫码支付、回调验签。第一个节点是下单接口。沙箱环境的下单逻辑和正式环境一样返回的qrCode可以直接渲染成二维码。用支付宝沙箱版App扫这个码就能模拟真实扫码动作。第二个节点是回调验证。沙箱支付成功后会主动回调本地环境前提是做了内网映射。第三个节点是业务幂等验证。连续模拟两次回调确认订单只更新一次库存只扣一次。还有一个偷懒但有效的技巧用模拟请求先测回调处理器。支付宝开放平台的控制台里沙箱应用有一个“模拟支付”入口可以手动触发支付成功通知不用真的扫码。但我的习惯是先用Postman构造一套带合法签名的回调请求打给本地接口验证验签、幂等、业务更新全链路再去真实支付。这样排错时能精确控制请求内容不用等支付宝的重发机制。日志追踪也值得养成习惯。这个项目里所有关键操作都围绕out_trade_no展开我在下单、二维码、回调三段逻辑里都打印同一个订单号// 下单阶段 log.info(order{} stageprecreate amount{} qrCodeLen{}, orderNo, amount, qrCode.length()); // 回调阶段 log.info(order{} stagenotify tradeStatus{} tradeNo{}, outTradeNo, tradeStatus, tradeNo); // 幂等跳过 log.warn(order{} stageduplicate_skip rows{}, outTradeNo, rows);出问题时直接在日志平台搜订单号就能看到这个订单从下单到支付完成的完整时间线。从那以后我每次接支付都强制在沙箱里把下单、扫码、回调、重复通知四条路径各跑一遍再切正式环境这套流程帮我省了不少上线后的排查时间。希望帮到你。本文还有配套的精品资源点击获取