简介面向Java开发者的支付宝扫码支付集成示例工程围绕扫码支付与刷脸支付相关说明提供从SDK引入、参数配置、二维码生成到支付回调处理的完整闭环。工程涵盖核心支付控制类、前端二维码展示页面以及多份配置文件可对照理解支付宝开放平台接入流程、appid与密钥管理方式。资源压缩包内共124个文件大小27.64MB以37个jar依赖库、23个Java源码、17个class文件为核心同时包含12个xml配置、10个js脚本、6个html页面、9个properties文件及2个css样式基本覆盖后端接口调试与前端页面联调所需素材。已有2483人学习下载。对于希望在电商、O2O等场景快速落地支付宝扫码支付的Java开发者这是一份可直接运行的示例工程从支付请求发起、二维码展示到异步回调处理均有对应代码可帮助梳理支付宝SDK调用、回调验签、订单状态同步以及支付安全处理等关键环节也可作为二次开发的基础骨架。1. Java集成支付宝扫码支付先把收钱跑通再谈刷脸奖励把 Java 集成支付宝扫码支付跑通再用同一套商户体系去对接支付宝刷脸支付官方奖励政策是我见过最适合服务商和独立后端团队的一条增长路线。扫码支付解决的是“能不能收钱”刷脸奖励解决的是“收了钱之后还能从官方多拿多少激励”。很多人卡在第一步以为下单接口返回一个二维码就结束了结果一到生产环境就被回调验签、订单状态、对账差异打回原形。这篇文章按我自己的落地顺序来写先用沙箱把预下单、回调、查单三个环节跑通再把高频踩坑列出来最后拆刷脸奖励的参与框架和算账模型。适合 Java 后端开发、支付服务商以及准备把门店支付场景做成项目的技术负责人。2. 支付宝扫码支付前置准备沙箱、密钥、模式选型一次说清开始写代码之前我建议先花半小时把支付宝开放平台里的角色关系理顺。你在开放平台注册的是“开发者”实际签约的是“商家”而真正调用接口的是你开发的“应用”。这三者不做区分后面配置密钥、申请产品权限时会反复绕圈。很多教程一上来就贴代码但你连 APPID 从哪里复制都不知道代码贴得再完整也只是黑匣子。2.1 先分清当面付、付款码、刷脸三条链路支付宝线下支付有三条经常被混在一起讲的链路。第一条是当面付的扫码支付接口名对应 alipay.trade.precreate。用户用支付宝 App 扫商家展示的二维码在手机上确认付款。这条链路对商户最友好线上 App、线下桌贴、自助机都能用Java 后端只需要做一次预下单拿到二维码链接交给前端渲染即可。第二条是付款码支付对应接口 alipay.trade.pay。收银员用扫码枪扫用户 App 里的付款码直接发起扣款。这条链路更适合超市、便利店因为它要求商户必须有扫码设备和收银系统而且对时序敏感付款码一码只能扫一次过期很快。第三条就是刷脸支付对应 face to face 相关的签约产品。用户在设备上刷脸设备端完成活体检测后调起支付服务端收到的通知结构与扫码支付高度相似。真正要做服务商生意我一般建议第一版只做第一链路也就是当面付扫码支付。原因是对硬件零依赖后端逻辑就是“预下单 → 用户付款 → 异步回调 → 更新订单”。等这条闭环跑通了再往付款码、刷脸扩展只是换接口和支付方式字段的事核心的订单处理和回调机制完全复用。2.2 支付宝沙箱支付环境把预下单到回调全流程跑通支付宝开放平台提供了沙箱环境也就是常说的支付宝沙箱支付。它不是模拟器而是一套真实可用的开放式接口环境支付不会真扣钱但接口行为和生产几乎一致。我第一次对接时就在沙箱里把预下单、回调、退款、对账全过了一遍省了不少学费。要进入沙箱先登录开放平台在开发中心创建一个应用绑定“当面付”产品能力然后打开沙箱页面的开关拿到沙箱 APPID、网关地址和测试账号。下面是我常用的最小 Maven 依赖。dependency groupIdcom.alipay.sdk/groupId artifactIdalipay-sdk-java/artifactId version4.39.77.ALL/version /dependency dependency groupIdcom.google.zxing/groupId artifactIdcore/artifactId version3.5.2/version /dependency dependency groupIdcom.google.zxing/groupId artifactIdjavase/artifactId version3.5.2/version /dependencyalipay-sdk-java 是官方 SDK4.x 主版本已经用了很多年4.39.77.ALL 是常见的一个稳定版本你的工程里可以按需升级。zxing 只用于把二维码链接转成图片如果前端已经能直接渲染 URL可以去掉后两个依赖。SDK 初始化建议单独拆成配置类方便沙箱和生产切换。Configuration public class AlipayConfig { Value(${alipay.app-id}) private String appId; Value(${alipay.private-key}) private String privateKey; Value(${alipay.public-key}) private String alipayPublicKey; Value(${alipay.gateway}) private String gateway; Bean public AlipayClient alipayClient() { return new DefaultAlipayClient(gateway, appId, privateKey, json, UTF-8, alipayPublicKey, RSA2); } }这里四个配置项分别是 APPID、应用私钥、支付宝公钥和网关地址。沙箱网关一般以 openapi.alipaydev.com 开头生产网关是 openapi.alipay.com。四个配置的详细说明如下表。配置项含义获取位置备注alipay.app-id应用唯一标识开放平台开发中心沙箱和生产各有一个alipay.private-key应用私钥用于请求签名开放平台密钥管理自己生成支付宝不保存alipay.public-key支付宝公钥用于验签开放平台密钥管理上传应用公钥后由平台生成alipay.gateway接口网关地址沙箱或生产环境常被漏配导致请求打错环境沙箱环境里有一个容易被忽略的配置回调地址 notify_url 虽然可以写 http://localhost但支付宝服务器无法访问到你的 localhost回调永远不会触发。我第一次就在沙箱里卡了两天后来借助内网穿透工具把本地端口暴露到公网回调才落到开发机。如果你所在网络不允许这种穿透可以先手动模拟回调把验签逻辑跑通。沙箱账号也分两种角色一个用于商家配置一个用于在沙箱 App 里模拟买家付款。重点记住每次在开放平台重置密钥后支付宝公钥都会变化环境切换后要重新复制否则验签就会失败。2.3 证书模式和公钥模式怎么选一次决定后续不折腾支付宝开放平台支持两种密钥方式公钥模式和证书模式。公钥模式就是上面代码展示的方式上传应用公钥保存支付宝公钥证书模式则用 appCertPublicKey、alipayCertPublicKey 和 rootCert 三份证书组合完成签名和验签。维度公钥模式证书模式配置复杂度低两个字符串搞定高三份文件要一起管理安全级别中公钥可被重新上传高证书更难替换更换流程重新上传公钥重新下载证书包适合场景个人开发、测试、小商户生产环境、服务商、高并发我的选择很简单个人项目和沙箱测试用公钥模式给商户做生产对接一律用证书模式。原因有两个一是证书模式对支付宝公钥更换有更好的容错二是服务商下面的多个应用统一用证书授权与轮换都更好管理。证书模式下 DefaultAlipayClient 的构造方法不同需要传入证书路径和对应公钥串这里不贴长代码只提醒一个原则证书路径建议放在 classpath 下用相对路径读取不要把证书塞进数据库或每次调用时重新加载否则性能瓶颈就在这冒出来。3. Java集成支付宝扫码支付的核心代码预下单、回调、查单三段闭环当面付扫码支付的 Java 实现核心就三个接口alipay.trade.precreate 预下单alipay.trade.query 查单再加上支付宝异步回调。把这三个点串起来订单状态机就完整了。下面是我在项目里长期使用的写法参数都带注释可以直接抄到自己的工程里改。3.1 预下单让用户扫你的码预下单的核心思路是你的服务端先向支付宝登记一笔订单支付宝返回一个二维码链接用户用支付宝 App 扫链接完成付款。关键点在于服务端没有直接扣款只是拿到了一个支付凭证。public String createQrCode(String outTradeNo, BigDecimal totalAmount, String subject) throws AlipayApiException { AlipayTradePrecreateRequest request new AlipayTradePrecreateRequest(); request.setNotifyUrl(https://api.example.com/alipay/notify); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); bizContent.put(total_amount, totalAmount.setScale(2, RoundingMode.HALF_UP).toString()); bizContent.put(subject, subject); bizContent.put(timeout_express, 5m); request.setBizContent(bizContent.toJSONString()); AlipayTradePrecreateResponse response alipayClient.execute(request); if (response.isSuccess()) { return response.getQrCode(); } throw new RuntimeException(预下单失败 response.getSubMsg()); }这段代码里total_amount 用 BigDecimal 转字符串避免浮点数精度问题timeout_express 设为 5m表示扫码后 5 分钟未支付就自动关闭。setNotifyUrl 是回调地址建议放到配置中心而不是写死。拿到 qrCode 后常规做法是把它生成二维码图片也可以直接返回给前端由前端二维码库渲染。如果你决定在服务端生成图片可以把 qrCode 交给 zxing 的 QRCodeWriter设置尺寸、编码和纠错级别输出到 BufferedImage 再转 base64 返回。注意二维码内容是一段 URL不要把它当成普通字符串直接展示在页面上。3.2 支付宝回调处理验签、幂等、改单支付宝异步回调是指用户支付成功后支付宝服务器会主动 POST 一段表单数据到你的 notify_url。你必须在收到通知时先验签再判断订单状态最后更新业务库并返回纯文本 success。这一步是 Java 面试八股文里常讲的点但实际项目最容易出问题。RequestMapping(value /alipay/notify, method RequestMethod.POST) public String alipayNotify(HttpServletRequest request) throws AlipayApiException { MapString, String params new HashMap(); MapString, String[] requestParams request.getParameterMap(); for (String name : requestParams.keySet()) { String[] values requestParams.get(name); params.put(name, String.join(,, values)); } boolean verified AlipaySignature.rsaCheckV1(params, alipayPublicKey, UTF-8, RSA2); if (!verified) { return failure; } String tradeStatus params.get(trade_status); String outTradeNo params.get(out_trade_no); String tradeNo params.get(trade_no); String amount params.get(total_amount); if (TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) { orderService.markPaid(outTradeNo, tradeNo, new BigDecimal(amount)); } return success; }预下单创建后 5 分钟未支付会自动关闭回调里的 tradeNo 是支付宝交易号你要把它和商户订单号 outTradeNo 一起存下来后面退款、对账都要用。markPaid 方法内部必须做幂等如果订单已经是已支付状态直接返回不要重复加余额。验签用的 alipayPublicKey 是支付宝公钥不是应用公钥这一点很容易配反。如果你的接口前面挂了 Nginx 反向代理要确保回调地址是公网域名并且不要在 Nginx 层做 GET/POST 重定向因为支付宝回调只接受 POST重定向会导致参数丢失。3.3 主动查单给回调兜底回调并不是 100% 可靠。网络抖动、回调地址超时、服务重启任何一个环节出问题都会导致订单卡在待支付。我的习惯是用户扫码后启动一个定时任务每分钟查一次订单状态直到超时或支付成功。public String queryOrder(String outTradeNo) throws AlipayApiException { AlipayTradeQueryRequest request new AlipayTradeQueryRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); request.setBizContent(bizContent.toJSONString()); AlipayTradeQueryResponse response alipayClient.execute(request); if (response.isSuccess()) { return response.getTradeStatus(); } return WAIT_BUYER_PAY; }查单接口返回 TRADE_SUCCESS、WAIT_BUYER_PAY、TRADE_CLOSED 等状态。定时任务在用户进入支付页后开启并且在订单表里记录 query_count超过比如 5 次就转入人工介入列表。为什么一定要主动查单因为如果支付宝侧已经扣款你这边却一直没收到回调不查单就没法恢复用户会投诉钱扣了但订单没生效。查单和回调两个机制配合才能把订单状态机兜住。常见做法是使用 Spring Scheduled 或 Quartz 做轮询服务端起多节点时要用分布式锁避免多个节点同时查同一笔订单。如果订单量不大用数据库唯一约束兜底也可以接受。4. 支付宝扫码支付常见问题排查5个坑逐个拆开这一章从生产环境的真实踩坑记录里挑出 5 个高频问题按照“现象 → 原因 → 解决”的顺序写。面试八股文只问原理真正让人头疼的是这些藏在角落里的细节。4.1 签名验证失败先查支付宝私钥和公钥是否有“错位”现象调用预下单时抛出 AlipayApiException异常信息里带 sign check fail 或类似关键字。很多人第一反应是算法选错了其实八成的场景是配置串了。原因你在开放平台上传的是应用公钥本地保存的是应用私钥支付宝返回的验签参数必须用支付宝公钥验证。很多新手把支付宝公钥复制到了 private-key 配置项里或者反过来。另一个原因是 YAML 缩进导致私钥字符串被截断没有完整读进内存。解决先在配置项前后打日志把 privateKey 的长度和首尾字符打出来和开放平台密钥管理页面里的内容比对。确认无误后再检查 AlipaySignature.rsaCheckV1 传入的是否为支付宝公钥。这一步用断点单步调试比在日志里猜快得多。4.2 回调通知收不到先查公网可见性和重试次数现象沙箱里用支付宝 App 扫码支付页面上显示支付成功服务端日志里没有任何回调请求。原因最常见的是 notify_url 写的是 localhost 或内网 IP支付宝服务器访问不到自然发不出通知。第二个原因是回调地址没有配置 HTTPS生产环境支付宝要求回调地址必须公网可访问且推荐 HTTPS沙箱环境对协议要求没那么严格但地址必须公网可达。解决把回调地址改成线上域名或者借助内网穿透工具暴露本地端口然后重新下一单。同时观察开放平台控制台里的“接口使用情况”能看出通知是否发出。如果地址没问题还是收不到检查回调接口是否被网关拦截、是否返回了非 success 的响应。支付宝对通知有 24 小时内的多次重试补偿但这不是持续的所以主动查单一定要做。4.3 报错“商家订单号重复”大概率是幂等没做现象沙箱里同一笔测试订单连续创建报 ACQ.TRADE_HAS_SUCCESS 或“商家订单号重复”。原因支付宝为了防重提交同一 out_trade_no 的订单只要处于未关闭状态再次发起预下单就会被拒绝。这个错误通常发生在用户快速连点两次提交或接口重试机制把同一订单号又发了一次。解决在自己系统里用全局订单号生成策略保证 out_trade_no 一定唯一。常见做法是雪花算法、Redis 自增 ID 或数据库序列。如果订单号生成方法没有加锁并发场景下可能产出相同订单号。要确保生成方法线程安全并且订单号里建议带业务标识方便排查问题成对出现。4.4 用户付了钱但订单没更新回调里的事务和返回码现象支付宝回调日志里显示 TRADE_SUCCESS但业务库里订单还是待支付或者余额加了但订单状态没改。原因回调处理函数里业务代码抛了异常导致整个事务回滚或者你在校验完参数后直接返回 success支付宝以为处理成功就不再重试而内部其实没落库。解决所有业务逻辑放在事务里幂等判断也在同一事务内。只有订单状态真正改成已支付、流水写完了才返回纯文本 success。如果返回 failure支付宝会按通知规则重试所以宁可重复消费也不要先返回成功再补数据。幂等可以这样写更新语句带上状态条件用受影响行数判断是否已经被处理过。UPDATE order SET status PAID, alipay_trade_no #{tradeNo} WHERE order_no #{orderNo} AND status WAIT_PAY这条 SQL 的巧妙之处在于并发重复回调时只有一个请求能更新成功另一个受影响行数为 0业务上直接忽略即可。注意回调里的 total_amount 是字符串不要用 Double 接收。4.5 金额精度问题用String接收用BigDecimal计算现象商户后台有的订单金额显示 109.999999有的显示 110.000000退款时差一分钱对不上账。原因接口参数 total_amount 是字符串你用 Double 接收或参与浮点运算精度就丢了。解决所有金额字段在 DTO 里都用 String 接收在业务里统一用 BigDecimal 计算并指定 ROUND_HALF_UP 保留两位。数据库字段用 decimal(10,2)不要用 double。退款接口传参时也要把 BigDecimal 转成字符串再提交。这个坑面试里经常问现实中不踩一次很难长记性。5. 支付宝刷脸支付官方奖励政策先懂规则再算账刷脸支付官方奖励政策本质上是一套市场推广补贴机制目的是让刷脸设备铺进线下门店让用户养成刷脸支付习惯。政策细节每个季度都可能调整所以这一章不给你具体数字只讲参与框架和算账方法。记住一个原则永远以支付宝开放平台当期的活动公告为准。5.1 官方奖励到底在奖励什么设备、有效交易还是场景从我接触过的几期活动来看奖励维度基本围绕三块转设备激活、有效交易、场景达标。设备激活指你在商户那里部署的刷脸终端完成首次激活有效交易指同一设备在活动周期内产生的符合规则的交易笔数或金额场景达标则是针对特定行业比如餐饮、零售、医疗门店在指定周期内达到一定交易量后触发额外梯度奖励。这三者里最容易误解的是“有效交易”。不是用户刷了脸就算规则通常会排除退款交易、撤销交易、单笔金额过小的交易甚至同一用户在同一设备的重复交易也可能只计一次。所以招商时不能直接跟商户承诺每台设备稳定收益要按笔均、客单、复购去保守估算。5.2 谁能领奖励服务商、商户、设备商的边界要参与政策先要搞清楚由谁去申报。支付宝开放平台的奖励默认跟支付宝服务商ISV签约结算而不是直接打给单个商户。你作为 Java 服务商要先完成开放平台的“服务商入驻”申请对应的产品能力然后把商户的支付宝账号授权绑定到你名下。这个过程叫商户授权授权成功后商户的交易才能关联到服务商的 PID 上。如果你是做设备的还得从支付宝认证的设备商渠道采购符合规范的刷脸设备。设备并不是随便买一台就能用支付宝要求的刷脸设备要经过官方认证包含摄像头、3D 结构光或红外活体检测模块设备厂商提供配套 SDK 和开发文档。Java 服务商通常不做硬件而是做设备里运行的刷脸收银应用需要对接设备商的认证 SDK。边界一句话总结你代理的是收单和数字化能力设备商代理的是硬件合规两边通过服务商协议绑定在一起。5.3 奖励金额怎么算用公式框架代替拍脑袋奖励政策的核算框架可以总结成一个公式总奖励 设备激活奖励 有效交易笔数奖励 场景达标奖励 - 无效交易扣除。设备激活奖励通常是每台设备激活后给一笔固定费用用来摊薄硬件成本有效交易笔数奖励按单笔或月累计梯度计算常见做法是把每月交易笔数分成几档档位越高单笔奖励越高场景达标奖励按行业和门店规模给比如连锁门店在指定时间内达到某个月交易额再额外奖励一部分。给商户做成本测算时我会把这三块拆开写进方案并且明确标注“以官方审核通过的数据为准”。这里有一个容易被忽视的滞后性奖励不是实时到账而是按自然月或活动周期结算审核过程中会扣掉退款率过高产生的交易。毛利极低的项目要控制设备投放数量否则补贴没下来资金早就压进去了。5.4 合规红线别为了奖励刷单审核会秋后算账做支付服务商最忌讳的就是刷单套补。官方政策里通常写得很清楚禁止虚假交易、禁止套现、禁止商户自身或员工在设备上进行与真实经营无关的支付操作。支付宝的风控体系不仅看设备维度还会看用户特征、交易时间、退款率一旦判定为虚假交易轻则扣减当期奖励重则取消服务商资质并追回已发放的补贴。我参与过一次设备铺放当时商户为了冲奖励收银员用自己支付宝反复扫码付款再退款结果那周交易全部被标记为无效连带我们服务商账号收到了风险提示。从那以后我在商户协议里明确写了一条如因商户原因导致服务商被追回奖励商户需要承担相应损失。这一步不是卡商户而是让所有参与方都建立合规预期。6. 从扫码到刷脸的改造复用订单体系用策略模式扩展扫码支付和刷脸支付在 Java 侧最大的不同是预下单接口不同但订单、回调、对账结构高度相似。所以做存量项目改造时复用订单体系和回调入口再用策略模式把支付方式抽象出来是成本最低的做法。6.1 最小改造把支付方式抽象成策略定义一个 PayStrategy 接口里面声明 createPayment(PayContext) 和 handleNotify(NotifyParams) 两个方法。扫码支付实现类和刷脸支付实现类分别填充原来的 Controller 回调入口保持不动只需要在报文里增加支付渠道字段然后从工厂里取对应的策略执行。public interface PayStrategy { String createPayment(PayContext context) throws AlipayApiException; boolean handleNotify(NotifyParams params) throws AlipayApiException; }这个改造对熟手来说半天能完成新手也值得认真写一版因为后面接付款码、声波支付时只需要加策略实现类不用动业务层。策略模式的关键是工厂和 Spring 容器配合通过 Component 注入而不是自己 new。6.2 验证清单沙箱、灰度、对账三步走上线前我会走三遍验证。第一遍在支付宝沙箱里用官方测试账号跑通预下单、回调、退款第二遍在真实商户小额灰度用一笔 0.01 元和一笔 0.22 元测试重点看金额精度和回调处理第三遍是对账每天下载支付宝账单和本地订单表做比对Diff 出多付、漏付和金额不一致的记录。我现在的习惯是任何支付类需求都必须写一个对账脚本哪怕只是 SQL。因为沙箱能验证接口但验证不了业务和时间的竞速只有对账才能真正兜住底。希望帮到你。本文还有配套的精品资源点击获取 Java集成支付宝扫码支付：从沙箱调试到刷脸奖励政策落地
简介面向Java开发者的支付宝扫码支付集成示例工程围绕扫码支付与刷脸支付相关说明提供从SDK引入、参数配置、二维码生成到支付回调处理的完整闭环。工程涵盖核心支付控制类、前端二维码展示页面以及多份配置文件可对照理解支付宝开放平台接入流程、appid与密钥管理方式。资源压缩包内共124个文件大小27.64MB以37个jar依赖库、23个Java源码、17个class文件为核心同时包含12个xml配置、10个js脚本、6个html页面、9个properties文件及2个css样式基本覆盖后端接口调试与前端页面联调所需素材。已有2483人学习下载。对于希望在电商、O2O等场景快速落地支付宝扫码支付的Java开发者这是一份可直接运行的示例工程从支付请求发起、二维码展示到异步回调处理均有对应代码可帮助梳理支付宝SDK调用、回调验签、订单状态同步以及支付安全处理等关键环节也可作为二次开发的基础骨架。1. Java集成支付宝扫码支付先把收钱跑通再谈刷脸奖励把 Java 集成支付宝扫码支付跑通再用同一套商户体系去对接支付宝刷脸支付官方奖励政策是我见过最适合服务商和独立后端团队的一条增长路线。扫码支付解决的是“能不能收钱”刷脸奖励解决的是“收了钱之后还能从官方多拿多少激励”。很多人卡在第一步以为下单接口返回一个二维码就结束了结果一到生产环境就被回调验签、订单状态、对账差异打回原形。这篇文章按我自己的落地顺序来写先用沙箱把预下单、回调、查单三个环节跑通再把高频踩坑列出来最后拆刷脸奖励的参与框架和算账模型。适合 Java 后端开发、支付服务商以及准备把门店支付场景做成项目的技术负责人。2. 支付宝扫码支付前置准备沙箱、密钥、模式选型一次说清开始写代码之前我建议先花半小时把支付宝开放平台里的角色关系理顺。你在开放平台注册的是“开发者”实际签约的是“商家”而真正调用接口的是你开发的“应用”。这三者不做区分后面配置密钥、申请产品权限时会反复绕圈。很多教程一上来就贴代码但你连 APPID 从哪里复制都不知道代码贴得再完整也只是黑匣子。2.1 先分清当面付、付款码、刷脸三条链路支付宝线下支付有三条经常被混在一起讲的链路。第一条是当面付的扫码支付接口名对应 alipay.trade.precreate。用户用支付宝 App 扫商家展示的二维码在手机上确认付款。这条链路对商户最友好线上 App、线下桌贴、自助机都能用Java 后端只需要做一次预下单拿到二维码链接交给前端渲染即可。第二条是付款码支付对应接口 alipay.trade.pay。收银员用扫码枪扫用户 App 里的付款码直接发起扣款。这条链路更适合超市、便利店因为它要求商户必须有扫码设备和收银系统而且对时序敏感付款码一码只能扫一次过期很快。第三条就是刷脸支付对应 face to face 相关的签约产品。用户在设备上刷脸设备端完成活体检测后调起支付服务端收到的通知结构与扫码支付高度相似。真正要做服务商生意我一般建议第一版只做第一链路也就是当面付扫码支付。原因是对硬件零依赖后端逻辑就是“预下单 → 用户付款 → 异步回调 → 更新订单”。等这条闭环跑通了再往付款码、刷脸扩展只是换接口和支付方式字段的事核心的订单处理和回调机制完全复用。2.2 支付宝沙箱支付环境把预下单到回调全流程跑通支付宝开放平台提供了沙箱环境也就是常说的支付宝沙箱支付。它不是模拟器而是一套真实可用的开放式接口环境支付不会真扣钱但接口行为和生产几乎一致。我第一次对接时就在沙箱里把预下单、回调、退款、对账全过了一遍省了不少学费。要进入沙箱先登录开放平台在开发中心创建一个应用绑定“当面付”产品能力然后打开沙箱页面的开关拿到沙箱 APPID、网关地址和测试账号。下面是我常用的最小 Maven 依赖。dependency groupIdcom.alipay.sdk/groupId artifactIdalipay-sdk-java/artifactId version4.39.77.ALL/version /dependency dependency groupIdcom.google.zxing/groupId artifactIdcore/artifactId version3.5.2/version /dependency dependency groupIdcom.google.zxing/groupId artifactIdjavase/artifactId version3.5.2/version /dependencyalipay-sdk-java 是官方 SDK4.x 主版本已经用了很多年4.39.77.ALL 是常见的一个稳定版本你的工程里可以按需升级。zxing 只用于把二维码链接转成图片如果前端已经能直接渲染 URL可以去掉后两个依赖。SDK 初始化建议单独拆成配置类方便沙箱和生产切换。Configuration public class AlipayConfig { Value(${alipay.app-id}) private String appId; Value(${alipay.private-key}) private String privateKey; Value(${alipay.public-key}) private String alipayPublicKey; Value(${alipay.gateway}) private String gateway; Bean public AlipayClient alipayClient() { return new DefaultAlipayClient(gateway, appId, privateKey, json, UTF-8, alipayPublicKey, RSA2); } }这里四个配置项分别是 APPID、应用私钥、支付宝公钥和网关地址。沙箱网关一般以 openapi.alipaydev.com 开头生产网关是 openapi.alipay.com。四个配置的详细说明如下表。配置项含义获取位置备注alipay.app-id应用唯一标识开放平台开发中心沙箱和生产各有一个alipay.private-key应用私钥用于请求签名开放平台密钥管理自己生成支付宝不保存alipay.public-key支付宝公钥用于验签开放平台密钥管理上传应用公钥后由平台生成alipay.gateway接口网关地址沙箱或生产环境常被漏配导致请求打错环境沙箱环境里有一个容易被忽略的配置回调地址 notify_url 虽然可以写 http://localhost但支付宝服务器无法访问到你的 localhost回调永远不会触发。我第一次就在沙箱里卡了两天后来借助内网穿透工具把本地端口暴露到公网回调才落到开发机。如果你所在网络不允许这种穿透可以先手动模拟回调把验签逻辑跑通。沙箱账号也分两种角色一个用于商家配置一个用于在沙箱 App 里模拟买家付款。重点记住每次在开放平台重置密钥后支付宝公钥都会变化环境切换后要重新复制否则验签就会失败。2.3 证书模式和公钥模式怎么选一次决定后续不折腾支付宝开放平台支持两种密钥方式公钥模式和证书模式。公钥模式就是上面代码展示的方式上传应用公钥保存支付宝公钥证书模式则用 appCertPublicKey、alipayCertPublicKey 和 rootCert 三份证书组合完成签名和验签。维度公钥模式证书模式配置复杂度低两个字符串搞定高三份文件要一起管理安全级别中公钥可被重新上传高证书更难替换更换流程重新上传公钥重新下载证书包适合场景个人开发、测试、小商户生产环境、服务商、高并发我的选择很简单个人项目和沙箱测试用公钥模式给商户做生产对接一律用证书模式。原因有两个一是证书模式对支付宝公钥更换有更好的容错二是服务商下面的多个应用统一用证书授权与轮换都更好管理。证书模式下 DefaultAlipayClient 的构造方法不同需要传入证书路径和对应公钥串这里不贴长代码只提醒一个原则证书路径建议放在 classpath 下用相对路径读取不要把证书塞进数据库或每次调用时重新加载否则性能瓶颈就在这冒出来。3. Java集成支付宝扫码支付的核心代码预下单、回调、查单三段闭环当面付扫码支付的 Java 实现核心就三个接口alipay.trade.precreate 预下单alipay.trade.query 查单再加上支付宝异步回调。把这三个点串起来订单状态机就完整了。下面是我在项目里长期使用的写法参数都带注释可以直接抄到自己的工程里改。3.1 预下单让用户扫你的码预下单的核心思路是你的服务端先向支付宝登记一笔订单支付宝返回一个二维码链接用户用支付宝 App 扫链接完成付款。关键点在于服务端没有直接扣款只是拿到了一个支付凭证。public String createQrCode(String outTradeNo, BigDecimal totalAmount, String subject) throws AlipayApiException { AlipayTradePrecreateRequest request new AlipayTradePrecreateRequest(); request.setNotifyUrl(https://api.example.com/alipay/notify); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); bizContent.put(total_amount, totalAmount.setScale(2, RoundingMode.HALF_UP).toString()); bizContent.put(subject, subject); bizContent.put(timeout_express, 5m); request.setBizContent(bizContent.toJSONString()); AlipayTradePrecreateResponse response alipayClient.execute(request); if (response.isSuccess()) { return response.getQrCode(); } throw new RuntimeException(预下单失败 response.getSubMsg()); }这段代码里total_amount 用 BigDecimal 转字符串避免浮点数精度问题timeout_express 设为 5m表示扫码后 5 分钟未支付就自动关闭。setNotifyUrl 是回调地址建议放到配置中心而不是写死。拿到 qrCode 后常规做法是把它生成二维码图片也可以直接返回给前端由前端二维码库渲染。如果你决定在服务端生成图片可以把 qrCode 交给 zxing 的 QRCodeWriter设置尺寸、编码和纠错级别输出到 BufferedImage 再转 base64 返回。注意二维码内容是一段 URL不要把它当成普通字符串直接展示在页面上。3.2 支付宝回调处理验签、幂等、改单支付宝异步回调是指用户支付成功后支付宝服务器会主动 POST 一段表单数据到你的 notify_url。你必须在收到通知时先验签再判断订单状态最后更新业务库并返回纯文本 success。这一步是 Java 面试八股文里常讲的点但实际项目最容易出问题。RequestMapping(value /alipay/notify, method RequestMethod.POST) public String alipayNotify(HttpServletRequest request) throws AlipayApiException { MapString, String params new HashMap(); MapString, String[] requestParams request.getParameterMap(); for (String name : requestParams.keySet()) { String[] values requestParams.get(name); params.put(name, String.join(,, values)); } boolean verified AlipaySignature.rsaCheckV1(params, alipayPublicKey, UTF-8, RSA2); if (!verified) { return failure; } String tradeStatus params.get(trade_status); String outTradeNo params.get(out_trade_no); String tradeNo params.get(trade_no); String amount params.get(total_amount); if (TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) { orderService.markPaid(outTradeNo, tradeNo, new BigDecimal(amount)); } return success; }预下单创建后 5 分钟未支付会自动关闭回调里的 tradeNo 是支付宝交易号你要把它和商户订单号 outTradeNo 一起存下来后面退款、对账都要用。markPaid 方法内部必须做幂等如果订单已经是已支付状态直接返回不要重复加余额。验签用的 alipayPublicKey 是支付宝公钥不是应用公钥这一点很容易配反。如果你的接口前面挂了 Nginx 反向代理要确保回调地址是公网域名并且不要在 Nginx 层做 GET/POST 重定向因为支付宝回调只接受 POST重定向会导致参数丢失。3.3 主动查单给回调兜底回调并不是 100% 可靠。网络抖动、回调地址超时、服务重启任何一个环节出问题都会导致订单卡在待支付。我的习惯是用户扫码后启动一个定时任务每分钟查一次订单状态直到超时或支付成功。public String queryOrder(String outTradeNo) throws AlipayApiException { AlipayTradeQueryRequest request new AlipayTradeQueryRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); request.setBizContent(bizContent.toJSONString()); AlipayTradeQueryResponse response alipayClient.execute(request); if (response.isSuccess()) { return response.getTradeStatus(); } return WAIT_BUYER_PAY; }查单接口返回 TRADE_SUCCESS、WAIT_BUYER_PAY、TRADE_CLOSED 等状态。定时任务在用户进入支付页后开启并且在订单表里记录 query_count超过比如 5 次就转入人工介入列表。为什么一定要主动查单因为如果支付宝侧已经扣款你这边却一直没收到回调不查单就没法恢复用户会投诉钱扣了但订单没生效。查单和回调两个机制配合才能把订单状态机兜住。常见做法是使用 Spring Scheduled 或 Quartz 做轮询服务端起多节点时要用分布式锁避免多个节点同时查同一笔订单。如果订单量不大用数据库唯一约束兜底也可以接受。4. 支付宝扫码支付常见问题排查5个坑逐个拆开这一章从生产环境的真实踩坑记录里挑出 5 个高频问题按照“现象 → 原因 → 解决”的顺序写。面试八股文只问原理真正让人头疼的是这些藏在角落里的细节。4.1 签名验证失败先查支付宝私钥和公钥是否有“错位”现象调用预下单时抛出 AlipayApiException异常信息里带 sign check fail 或类似关键字。很多人第一反应是算法选错了其实八成的场景是配置串了。原因你在开放平台上传的是应用公钥本地保存的是应用私钥支付宝返回的验签参数必须用支付宝公钥验证。很多新手把支付宝公钥复制到了 private-key 配置项里或者反过来。另一个原因是 YAML 缩进导致私钥字符串被截断没有完整读进内存。解决先在配置项前后打日志把 privateKey 的长度和首尾字符打出来和开放平台密钥管理页面里的内容比对。确认无误后再检查 AlipaySignature.rsaCheckV1 传入的是否为支付宝公钥。这一步用断点单步调试比在日志里猜快得多。4.2 回调通知收不到先查公网可见性和重试次数现象沙箱里用支付宝 App 扫码支付页面上显示支付成功服务端日志里没有任何回调请求。原因最常见的是 notify_url 写的是 localhost 或内网 IP支付宝服务器访问不到自然发不出通知。第二个原因是回调地址没有配置 HTTPS生产环境支付宝要求回调地址必须公网可访问且推荐 HTTPS沙箱环境对协议要求没那么严格但地址必须公网可达。解决把回调地址改成线上域名或者借助内网穿透工具暴露本地端口然后重新下一单。同时观察开放平台控制台里的“接口使用情况”能看出通知是否发出。如果地址没问题还是收不到检查回调接口是否被网关拦截、是否返回了非 success 的响应。支付宝对通知有 24 小时内的多次重试补偿但这不是持续的所以主动查单一定要做。4.3 报错“商家订单号重复”大概率是幂等没做现象沙箱里同一笔测试订单连续创建报 ACQ.TRADE_HAS_SUCCESS 或“商家订单号重复”。原因支付宝为了防重提交同一 out_trade_no 的订单只要处于未关闭状态再次发起预下单就会被拒绝。这个错误通常发生在用户快速连点两次提交或接口重试机制把同一订单号又发了一次。解决在自己系统里用全局订单号生成策略保证 out_trade_no 一定唯一。常见做法是雪花算法、Redis 自增 ID 或数据库序列。如果订单号生成方法没有加锁并发场景下可能产出相同订单号。要确保生成方法线程安全并且订单号里建议带业务标识方便排查问题成对出现。4.4 用户付了钱但订单没更新回调里的事务和返回码现象支付宝回调日志里显示 TRADE_SUCCESS但业务库里订单还是待支付或者余额加了但订单状态没改。原因回调处理函数里业务代码抛了异常导致整个事务回滚或者你在校验完参数后直接返回 success支付宝以为处理成功就不再重试而内部其实没落库。解决所有业务逻辑放在事务里幂等判断也在同一事务内。只有订单状态真正改成已支付、流水写完了才返回纯文本 success。如果返回 failure支付宝会按通知规则重试所以宁可重复消费也不要先返回成功再补数据。幂等可以这样写更新语句带上状态条件用受影响行数判断是否已经被处理过。UPDATE order SET status PAID, alipay_trade_no #{tradeNo} WHERE order_no #{orderNo} AND status WAIT_PAY这条 SQL 的巧妙之处在于并发重复回调时只有一个请求能更新成功另一个受影响行数为 0业务上直接忽略即可。注意回调里的 total_amount 是字符串不要用 Double 接收。4.5 金额精度问题用String接收用BigDecimal计算现象商户后台有的订单金额显示 109.999999有的显示 110.000000退款时差一分钱对不上账。原因接口参数 total_amount 是字符串你用 Double 接收或参与浮点运算精度就丢了。解决所有金额字段在 DTO 里都用 String 接收在业务里统一用 BigDecimal 计算并指定 ROUND_HALF_UP 保留两位。数据库字段用 decimal(10,2)不要用 double。退款接口传参时也要把 BigDecimal 转成字符串再提交。这个坑面试里经常问现实中不踩一次很难长记性。5. 支付宝刷脸支付官方奖励政策先懂规则再算账刷脸支付官方奖励政策本质上是一套市场推广补贴机制目的是让刷脸设备铺进线下门店让用户养成刷脸支付习惯。政策细节每个季度都可能调整所以这一章不给你具体数字只讲参与框架和算账方法。记住一个原则永远以支付宝开放平台当期的活动公告为准。5.1 官方奖励到底在奖励什么设备、有效交易还是场景从我接触过的几期活动来看奖励维度基本围绕三块转设备激活、有效交易、场景达标。设备激活指你在商户那里部署的刷脸终端完成首次激活有效交易指同一设备在活动周期内产生的符合规则的交易笔数或金额场景达标则是针对特定行业比如餐饮、零售、医疗门店在指定周期内达到一定交易量后触发额外梯度奖励。这三者里最容易误解的是“有效交易”。不是用户刷了脸就算规则通常会排除退款交易、撤销交易、单笔金额过小的交易甚至同一用户在同一设备的重复交易也可能只计一次。所以招商时不能直接跟商户承诺每台设备稳定收益要按笔均、客单、复购去保守估算。5.2 谁能领奖励服务商、商户、设备商的边界要参与政策先要搞清楚由谁去申报。支付宝开放平台的奖励默认跟支付宝服务商ISV签约结算而不是直接打给单个商户。你作为 Java 服务商要先完成开放平台的“服务商入驻”申请对应的产品能力然后把商户的支付宝账号授权绑定到你名下。这个过程叫商户授权授权成功后商户的交易才能关联到服务商的 PID 上。如果你是做设备的还得从支付宝认证的设备商渠道采购符合规范的刷脸设备。设备并不是随便买一台就能用支付宝要求的刷脸设备要经过官方认证包含摄像头、3D 结构光或红外活体检测模块设备厂商提供配套 SDK 和开发文档。Java 服务商通常不做硬件而是做设备里运行的刷脸收银应用需要对接设备商的认证 SDK。边界一句话总结你代理的是收单和数字化能力设备商代理的是硬件合规两边通过服务商协议绑定在一起。5.3 奖励金额怎么算用公式框架代替拍脑袋奖励政策的核算框架可以总结成一个公式总奖励 设备激活奖励 有效交易笔数奖励 场景达标奖励 - 无效交易扣除。设备激活奖励通常是每台设备激活后给一笔固定费用用来摊薄硬件成本有效交易笔数奖励按单笔或月累计梯度计算常见做法是把每月交易笔数分成几档档位越高单笔奖励越高场景达标奖励按行业和门店规模给比如连锁门店在指定时间内达到某个月交易额再额外奖励一部分。给商户做成本测算时我会把这三块拆开写进方案并且明确标注“以官方审核通过的数据为准”。这里有一个容易被忽视的滞后性奖励不是实时到账而是按自然月或活动周期结算审核过程中会扣掉退款率过高产生的交易。毛利极低的项目要控制设备投放数量否则补贴没下来资金早就压进去了。5.4 合规红线别为了奖励刷单审核会秋后算账做支付服务商最忌讳的就是刷单套补。官方政策里通常写得很清楚禁止虚假交易、禁止套现、禁止商户自身或员工在设备上进行与真实经营无关的支付操作。支付宝的风控体系不仅看设备维度还会看用户特征、交易时间、退款率一旦判定为虚假交易轻则扣减当期奖励重则取消服务商资质并追回已发放的补贴。我参与过一次设备铺放当时商户为了冲奖励收银员用自己支付宝反复扫码付款再退款结果那周交易全部被标记为无效连带我们服务商账号收到了风险提示。从那以后我在商户协议里明确写了一条如因商户原因导致服务商被追回奖励商户需要承担相应损失。这一步不是卡商户而是让所有参与方都建立合规预期。6. 从扫码到刷脸的改造复用订单体系用策略模式扩展扫码支付和刷脸支付在 Java 侧最大的不同是预下单接口不同但订单、回调、对账结构高度相似。所以做存量项目改造时复用订单体系和回调入口再用策略模式把支付方式抽象出来是成本最低的做法。6.1 最小改造把支付方式抽象成策略定义一个 PayStrategy 接口里面声明 createPayment(PayContext) 和 handleNotify(NotifyParams) 两个方法。扫码支付实现类和刷脸支付实现类分别填充原来的 Controller 回调入口保持不动只需要在报文里增加支付渠道字段然后从工厂里取对应的策略执行。public interface PayStrategy { String createPayment(PayContext context) throws AlipayApiException; boolean handleNotify(NotifyParams params) throws AlipayApiException; }这个改造对熟手来说半天能完成新手也值得认真写一版因为后面接付款码、声波支付时只需要加策略实现类不用动业务层。策略模式的关键是工厂和 Spring 容器配合通过 Component 注入而不是自己 new。6.2 验证清单沙箱、灰度、对账三步走上线前我会走三遍验证。第一遍在支付宝沙箱里用官方测试账号跑通预下单、回调、退款第二遍在真实商户小额灰度用一笔 0.01 元和一笔 0.22 元测试重点看金额精度和回调处理第三遍是对账每天下载支付宝账单和本地订单表做比对Diff 出多付、漏付和金额不一致的记录。我现在的习惯是任何支付类需求都必须写一个对账脚本哪怕只是 SQL。因为沙箱能验证接口但验证不了业务和时间的竞速只有对账才能真正兜住底。希望帮到你。本文还有配套的精品资源点击获取