简介这套Java集成支付宝扫码支付项目面向需要为电商、O2O等业务接入扫码支付的Java开发者完整演示了从支付宝SDK调用、订单发起、二维码生成到异步回调处理的全流程并附有可直接运行的前后端代码样例。资源包共124个文件约27.64MB内含37个jar依赖库、23个java源码、17个class文件以及xml配置、properties参数文件、前端html/js/css页面等既有后端Controller/Model/工具类也有展示二维码与支付状态的页面结构。已有2483人学习下载适合正在开发支付功能并希望理解支付宝接口交互、回调同步与安全细节的中高级Java工程师。通过源码可快速掌握appid与密钥配置、扫码支付请求构建、异步通知验签及订单状态更新等关键环节还能参考项目中的日志和配置文件规范减少联调踩坑适合作为支付模块的开发蓝本。1. Java接入支付宝扫码支付为什么沙箱总在第一步卡住很多Java后端第一次接触支付宝扫码支付以为就是调一个接口、把返回的二维码字符串丢给前端结果光是“应用私钥”和“支付宝公钥”的对应关系就折腾了一下午。这里说的扫码支付是当面付里的“扫码支付”场景商家系统生成二维码用户用支付宝扫一下支付成功后支付宝异步回调通知服务端。这条链路包含预下单、回调查验、订单状态更新和沙箱联调每一步都有细节。这篇文章就从零把这条链路讲透覆盖参数配置、核心代码、常见踩坑最后再说说支付宝刷脸支付官方奖励政策这个与扫码支付紧密相关的新入口。适合正在给公司做支付模块或者在课设项目里想接真实支付流程的Java开发。2. 把支付宝密钥配明白沙箱环境、应用私钥与SDK初始化2.1 先分清三个环境真实环境、沙箱、模拟器接入支付宝支付之前先要在开放平台确认自己处在哪个环境。常见做法是开发阶段用沙箱联调用沙箱App正式上线前切到真实应用。沙箱环境和真实环境的AppId、密钥、网关地址都是独立的混用是新手最容易踩的第一个坑。沙箱环境里支付宝会给你一套测试应用也提供沙箱钱包用于模拟扫码支付。很多人把正式环境的应用私钥复制进沙箱配置结果下单报“密钥格式错误”。判断当前环境最简单的办法是看网关地址真实环境是openapi.alipay.com沙箱环境是openapi.alipaydev.com具体域名以开放平台当前文档为准。项目里建议把这两套配置拆成不同的Spring Profile避免上线时手工改漏。模拟器这边要留意只使用支付宝官方沙箱App或官方提供的测试工具不要下载来历不明的“支付宝模拟器”。那些非官方工具可能伪造支付结果用来应付学校作业还行一旦拿它测试回调逻辑很容易被假通知带偏让你误以为集成已经通了。2.2 生成RSA2密钥并搞清应用公钥和支付宝公钥密钥环节是整条链路里最玄学的部分但说透了就两点签名用自己的私钥验签用支付宝的公钥。你生成的是RSA2密钥对在开放平台配置的是应用公钥支付宝用自己的私钥加签平台会返回一个支付宝公钥给应用。很多报错来自把应用公钥当支付宝公钥用导致验签永远失败。生成密钥时建议用支付宝官方密钥工具工具会同时生成应用私钥、应用公钥和PKCS8格式的私钥字符串。配置到项目里的私钥必须是PKCS8格式如果是Java项目才可以直接塞进配置。私钥字符串里包含换行符在YAML里最好用单引号包住或者把换行替换成字面的“\n”这一步看着小翻车率很高。拿到支付宝公钥后可以先手动验签测一下用同一个私钥对一段固定字符串加签再用支付宝公钥对应用公钥做校验。SDK初始化时alipayPublicKey参数填的必须是开放平台“应用详情—开发设置—接口加签方式”里展示的支付宝公钥不是你上传的那个应用公钥。区分不了这两个后面所有接口都跑不通。2.3 引入SDK并写出一个可靠的AlipayClient配置类Maven依赖里使用com.alipay.sdk:alipay-sdk-java版本用4.x即可具体版本号以Maven Central为准。SDK本身是黑匣子但初始化方式很固定通过DefaultAlipayClient创建客户端所有请求都由它发出。Configuration ConfigurationProperties(prefix alipay) public class AlipayConfig { private String appId; private String privateKey; private String alipayPublicKey; private String serverUrl; private String notifyUrl; private String signType RSA2; Bean public AlipayClient alipayClient() { return new DefaultAlipayClient( serverUrl, appId, privateKey, json, UTF-8, alipayPublicKey, signType ); } // getter 和 setter 省略 }这段代码的逻辑很清楚serverUrl决定了请求打到真实环境还是沙箱appId对应开放平台创建的应用privateKey是应用私钥alipayPublicKey是支付宝公钥signType固定RSA2。DefaultAlipayClient初始化时不会联网配置错误只会在第一次调用接口时显现。在application.yml里对应写入alipay: server-url: https://openapi.alipaydev.com/gateway.do app-id: 2021000123456789 private-key: MIIEvQIBADANBg... alipay-public-key: MIIBIjANBg... notify-url: https://api.example.com/alipay/notify sign-type: RSA2notifyUrl必须是可以被公网访问的地址回调时支付宝只认这个配置。沙箱环境同样要求公网可达本地开发阶段可以用内网穿透工具把本机映射出去。启动项目前先确认这些参数都能从环境变量读取不要把私钥提交到Git仓库这是上线前必须检查的一关。3. 扫码支付两段操作预下单生成二维码异步回调更新订单3.1 选对下单接口当面付扫码 vs 电脑网站支付支付宝扫码支付在不同场景下对应不同接口。如果是线下收银用户用手机扫商家屏幕上的二维码一般走当面付的alipay.trade.precreate这个接口返回一段二维码字符串由前端渲染成二维码。如果是PC网站用户支付宝App扫码付款通常用电脑网站支付alipay.trade.page.pay它会返回一个跳转表单给浏览器。标题里的“扫码支付”在我的实践里默认按当面付的扫码支付来做因为它的集成链路更短也更容易在沙箱里完整走通。电脑网站支付的区别是下单后返回的不是二维码字符串而是一段HTML表单需要处理重定向当面付扫码返回的二维码串则可以直接交给前端qrcode库渲染对前后端都更友好。选择接口还要注意签约状态。当面付和电脑网站支付在开放平台是不同的产品需要分别签约。如果在沙箱里测试签约状态一般由沙箱环境自动开通不额外收费线上环境必须先在开放平台完成对应产品的签约否则调用接口会报“产品未开通”。3.2 预下单参数、签名与二维码返回在Service层封装一个createPayQrCode方法入参是业务订单号和支付金额。这里的金额必须是字符串单位是元支付宝不接受任何浮点数运算结果。我习惯在Service层先从数据库读取订单金额再转成字符串传给支付宝绝不使用前端传来的金额字段这样可以避免金额被篡改和浮点精度问题。Service public class AlipayScanPayService { private final AlipayClient alipayClient; private final AlipayConfig alipayConfig; public AlipayScanPayService(AlipayClient alipayClient, AlipayConfig alipayConfig) { this.alipayClient alipayClient; this.alipayConfig alipayConfig; } public String createQrCode(String outTradeNo, String totalAmount, String subject) throws AlipayApiException { AlipayTradePrecreateRequest request new AlipayTradePrecreateRequest(); request.setNotifyUrl(alipayConfig.getNotifyUrl()); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); bizContent.put(total_amount, totalAmount); bizContent.put(subject, subject); // 超时时间单位为分钟建议使用动态值 bizContent.put(timeout_express, 15m); request.setBizContent(bizContent.toJSONString()); AlipayTradePrecreateResponse response alipayClient.execute(request); if (!response.isSuccess()) { throw new RuntimeException(支付宝下单失败 response.getSubMsg()); } return response.getQrCode(); } }这段代码的关键参数解释out_trade_no是商户订单号必须全局唯一重复下单会被支付宝拒绝total_amount是订单金额精确到分比如0.01表示一分钱subject会显示在用户账单里timeout_express设置订单过期时间我一般设置15分钟用户扫码后超过这个时间未支付支付宝会自动关闭避免僵尸订单占用库里的订单状态。接口返回的response.getQrCode()是一串文本形式的二维码内容不是图片。前端拿到后用JavaScript库画到页面或打印成小票二维码里包含的是支付宝的支付短链接。这一步做完扫码支付的“下单”部分就结束了剩下的是被动等支付宝回调。3.3 异步回调验签、金额比对、幂等更新支付宝扫码支付成功后会以POST表单形式异步访问notifyUrl参数是平铺的Map。Controller 接收到请求后必须第一时间验签验签通过才能处理业务数据。PostMapping(/alipay/notify) public String handleNotify(RequestParam MapString, String params) throws AlipayApiException { // 1. 验签防止伪造回调 boolean signPass AlipaySignature.rsaCheckV1( params, alipayConfig.getAlipayPublicKey(), UTF-8, alipayConfig.getSignType() ); if (!signPass) { return failure; } // 2. 业务校验 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); // 这里从数据库取订单比较 totalAmount 是否一致 Order order orderService.getByOutTradeNo(outTradeNo); if (order null) { return failure; } if (!new BigDecimal(order.getAmount()).equals(new BigDecimal(totalAmount))) { return failure; } // 3. 幂等更新只有待支付状态才更新 if ((TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) WAIT_PAY.equals(order.getStatus())) { orderService.markPaid(outTradeNo, tradeNo); } // 4. 必须返回 success 纯文本 return success; }逻辑说明rsaCheckV1内部会用支付宝公钥对参数签名做验证它要求传入的Map里包含原始的sign字段SDK会自己剔除。第二步业务校验最重要线上收到的回调可能是伪造的即使验签通过也必须比对金额和订单号。第三步用状态条件实现幂等支付宝在支付成功后可能会多次通知同一个结果重复执行会导致状态覆盖或重复发货所以必须要求当前订单是“待支付”状态才更新。参数解释trade_no是支付宝交易号它会跟随这笔订单终身生效退款、对账都会用到所以要存入订单表。trade_status在TRADE_SUCCESS时表示支付成功TRADE_FINISHED表示支付完成且退款额度已用完两种状态对你来说都算已支付。如果代码里没做幂等可以用一张pay_notify_log表记录支付宝交易号再配合唯一索引比单纯依赖状态判断更稳。4. 支付宝扫码支付接入避坑五个让订单对不上的问题4.1 私钥与签名相关的“玄学”报错现象沙箱里下单立刻报“签名验证失败”或者收到回调后rsaCheckV1一直返回false。原因最常见的是把应用公钥当支付宝公钥使用还有私钥没有用PKCS8格式以及YAML里private-key用了双引号导致换行转义错误。解决回到开放平台开发设置里重新复制支付宝公钥注意是一整串MIIB...开头的字符。Java代码里直接用PKCS8私钥字符串并在YAML中加单引号。如果已经生成了PKCS1格式私钥用工具转换成PKCS8再贴过来。我用过最稳妥的办法是把私钥放到环境变量而不是YAML里启动时通过Value注入既避免换行问题也避免误提交。4.2 下单成功但二维码扫不出来现象前端把response.getQrCode()当成了普通字符串放入二维码生成库扫出来是一个网页但页面提示“无法验证应用”或直接白屏。原因有些前端实现会把二维码内容再次编码或使用了不兼容的渲染组件。支付宝二维码内容本身是支付链接不需要前端二次加工。解决前端用qrcode库直接渲染字符串图片尺寸不要小于200x200确保用户能用支付宝扫。如果页面是PC端可以增加“保存二维码”按钮如果用户用的是微信扫一扫会提示无法识别这属于正常现象并不是支付服务的问题。二维码有效期受timeout_express控制过期后扫出来提示订单关闭需要回到下单页重新生成。4.3 沙箱支付后收不到回调现象用沙箱钱包扫码付款成功本地项目日志里完全没有/alipay/notify的访问记录。原因支付宝回调要求notify_url能公网访问。本地开发localhost地址支付宝访问不到很多人以为配置了沙箱环境就可以回调到本地这是没弄明白回调链路。解决本地开发可以用内网穿透工具把本机端口映射成公网地址然后把该地址填到notify_url。注意穿透工具的免费域名不稳定如果项目在服务器上直接把notify_url指向一个测试环境的域名。回调地址后面不要带query参数支付宝会在notify_url后拼接自己的参数如果地址本身带参数容易出问题。4.4 重复回调造成订单状态错乱现象同一个订单支付宝回调了三次数据库里订单从“已支付”被改成了“退款中”或者发货逻辑被执行多次。原因支付宝的异步通知为了可靠性会重复发送间隔时间递增直到应用返回success。如果业务处理写得不幂等重复通知就会带来脏更新。解决在更新订单的SQL里带上状态条件例如update order set status PAID where out_trade_no ? and status WAIT_PAY。同时维护一张回调通知表记录trade_no和本次回调的参数摘要用trade_no加唯一索引第一次插入成功才继续业务逻辑后面重复插入直接跳过。如果订单存在退款逻辑状态机要设计成单向流转避免把已支付状态又改回待支付。4.5 金额比对把单位搞混现象用户支付0.01元数据库订单金额是0.01但回调里total_amount是1.00比对不通过导致回调失败。原因支付宝回调金额单位是元字符串形式。有些开发把数据库金额存成“分”或者前端把金额转成了Double结果0.01变成了0.010000000000000000208。解决下单和回调比对统一以“元”为单位用BigDecimal比较不要用equals因为字符串0.01和0.010在BigDecimal里相等性判断也依赖精度。更稳妥的做法是数据库保存金额单位是“分”在传给支付宝时转换为“元”字符串回调时再把total_amount乘以100转为“分”来比对。我自己的项目里统一用的是BigDecimal并设置为两位小数避免任何浮点运算。5. 从扫码支付到刷脸支付官方奖励政策的获取路径与Java侧改动5.1 刷脸支付不是另一套支付体系只是换了收款交互很多Java后端一听到“支付宝刷脸支付”就以为是新SDK、新协议实际上刷脸支付的资金链路依然是支付宝交易接口刷脸设备帮你完成了原本需要用户扫码的那一步。后端处理的核心逻辑还是预下单、异步回调、验签、更新订单。换句话说你把扫码支付集成好后刷脸支付的服务端改动没有想象中那么大。区别体验在设备端扫码支付是用户手机主动扫商家二维码刷脸支付是用户在蜻蜓等设备上确认刷脸。设备会调用支付宝开放能力最终仍然由支付宝向业务系统的notify_url发起支付结果通知。所以回调验签、订单幂等、对账脚本这些代码直接从扫码支付项目里复用过来即可不需要重写。5.2 官方奖励政策怎么查、怎么核对“支付宝刷脸支付官方奖励政策”经常出现在服务商和商家的讨论里它的核心是服务商或商户在指定时间内推广刷脸设备、产生有效交易支付宝会给予一定比例或固定金额的奖励。这类政策是阶段性活动会调整不存在一个固定不变的奖励标准所以任何文章或截图告诉你“刷脸一台返xxx元”都需要警惕。获取官方信息只能看三个渠道支付宝开放平台官网的公告中心、服务商后台的运营活动模块以及与你签约的支付宝业务经理提供的合同文档。开放平台域名是open.alipay.com不要点陌生短信里的“刷脸奖励领取”链接。核对政策时要关注这几个字段适用设备型号、活动开始和结束时间、有效交易定义、奖励核算周期、结算方式。开发侧没必要深入研究每一条但要把订单表里的支付设备类型和交易时间保留好作为后续核算的数据来源。5.3 服务端要提前准备的三个改动如果你计划在扫码支付项目里扩展刷脸支付我建议先把下面三件事做了。第一订单表增加device_id和pay_type字段刷脸支付回调里会带上设备号你可以在回调验签后把它存下来第二配置一个新的notify_url给刷脸设备产品使用方便在日志里按来源区分设备避免和扫码支付的通知混在一起第三在开放平台单独申请刷脸支付相关的产品权限扫码支付签约并不代表刷脸支付自动开通。// 在回调参数中读取设备号用于统计设备有效交易 String deviceId params.get(device_id); if (StringUtils.hasText(deviceId)) { orderService.updateDeviceId(outTradeNo, deviceId); }这段代码放在验签和金额校验之后更新订单状态之前。device_id是支付宝返回的设备唯一标识刷脸支付政策里的“有效动账”统计会依赖它。提前把这些字段存下来后续即使奖励政策调整也能在后台导出交易明细进行核对而不是等到需要统计时才发现日志里没有设备维度。另外沙箱环境通常不提供真实的刷脸设备测试时可以用开放平台提供的刷脸Stub工具或联系业务经理开通测试设备。不要自行下载非官方刷脸App避免账号风险。6. 上线前必须做的验证主动查单与对账兜底扫码支付集成完毕后不能只在沙箱里付款成功就算结束。我的习惯是在上线前把“主动查单”加上因为支付宝回调不是百分之百即时到达网络抖动或服务器重启都可能造成通知丢失。主动查单的逻辑很简单对本地“待支付”订单启动定时任务每5分钟调用一次alipay.trade.query接口如果返回TRADE_SUCCESS就手动执行和回调一样的订单更新逻辑。Scheduled(fixedDelay 300000) public void handleTimeoutOrders() { ListOrder waitPayOrders orderService.listWaitPay(); for (Order order : waitPayOrders) { AlipayTradeQueryRequest request new AlipayTradeQueryRequest(); request.setBizContent({\out_trade_no\:\ order.getOrderNo() \}); AlipayTradeQueryResponse response alipayClient.execute(request); if (TRADE_SUCCESS.equals(response.getTradeStatus())) { orderService.markPaid(order.getOrderNo(), response.getTradeNo()); } } }这段代码里用到定时任务主启动类上需要加EnableScheduling。查询接口没有回调那么多校验但仍要判断trade_status和金额。把主动查单和回调更新放在同一个事务方法里执行保证重复通知时两个途径最终结果一致。另一个有用的验证方法是对账单支付宝开放平台会提供按日汇总的账单文件可以下载下来和本地订单表做比对。对账金额一致说明这条支付链路已经稳定了不一致再进订单日志排查。我第一次接支付时只做了回调上线第二天就发现红冲订单没处理后面补了对账脚本才真正安心。现在每个项目我都会先做主动查单再做对账这让我少熬了很多夜。希望帮到你。本文还有配套的精品资源点击获取 Java接入支付宝扫码支付：从沙箱配置到异步回调验签全攻略
简介这套Java集成支付宝扫码支付项目面向需要为电商、O2O等业务接入扫码支付的Java开发者完整演示了从支付宝SDK调用、订单发起、二维码生成到异步回调处理的全流程并附有可直接运行的前后端代码样例。资源包共124个文件约27.64MB内含37个jar依赖库、23个java源码、17个class文件以及xml配置、properties参数文件、前端html/js/css页面等既有后端Controller/Model/工具类也有展示二维码与支付状态的页面结构。已有2483人学习下载适合正在开发支付功能并希望理解支付宝接口交互、回调同步与安全细节的中高级Java工程师。通过源码可快速掌握appid与密钥配置、扫码支付请求构建、异步通知验签及订单状态更新等关键环节还能参考项目中的日志和配置文件规范减少联调踩坑适合作为支付模块的开发蓝本。1. Java接入支付宝扫码支付为什么沙箱总在第一步卡住很多Java后端第一次接触支付宝扫码支付以为就是调一个接口、把返回的二维码字符串丢给前端结果光是“应用私钥”和“支付宝公钥”的对应关系就折腾了一下午。这里说的扫码支付是当面付里的“扫码支付”场景商家系统生成二维码用户用支付宝扫一下支付成功后支付宝异步回调通知服务端。这条链路包含预下单、回调查验、订单状态更新和沙箱联调每一步都有细节。这篇文章就从零把这条链路讲透覆盖参数配置、核心代码、常见踩坑最后再说说支付宝刷脸支付官方奖励政策这个与扫码支付紧密相关的新入口。适合正在给公司做支付模块或者在课设项目里想接真实支付流程的Java开发。2. 把支付宝密钥配明白沙箱环境、应用私钥与SDK初始化2.1 先分清三个环境真实环境、沙箱、模拟器接入支付宝支付之前先要在开放平台确认自己处在哪个环境。常见做法是开发阶段用沙箱联调用沙箱App正式上线前切到真实应用。沙箱环境和真实环境的AppId、密钥、网关地址都是独立的混用是新手最容易踩的第一个坑。沙箱环境里支付宝会给你一套测试应用也提供沙箱钱包用于模拟扫码支付。很多人把正式环境的应用私钥复制进沙箱配置结果下单报“密钥格式错误”。判断当前环境最简单的办法是看网关地址真实环境是openapi.alipay.com沙箱环境是openapi.alipaydev.com具体域名以开放平台当前文档为准。项目里建议把这两套配置拆成不同的Spring Profile避免上线时手工改漏。模拟器这边要留意只使用支付宝官方沙箱App或官方提供的测试工具不要下载来历不明的“支付宝模拟器”。那些非官方工具可能伪造支付结果用来应付学校作业还行一旦拿它测试回调逻辑很容易被假通知带偏让你误以为集成已经通了。2.2 生成RSA2密钥并搞清应用公钥和支付宝公钥密钥环节是整条链路里最玄学的部分但说透了就两点签名用自己的私钥验签用支付宝的公钥。你生成的是RSA2密钥对在开放平台配置的是应用公钥支付宝用自己的私钥加签平台会返回一个支付宝公钥给应用。很多报错来自把应用公钥当支付宝公钥用导致验签永远失败。生成密钥时建议用支付宝官方密钥工具工具会同时生成应用私钥、应用公钥和PKCS8格式的私钥字符串。配置到项目里的私钥必须是PKCS8格式如果是Java项目才可以直接塞进配置。私钥字符串里包含换行符在YAML里最好用单引号包住或者把换行替换成字面的“\n”这一步看着小翻车率很高。拿到支付宝公钥后可以先手动验签测一下用同一个私钥对一段固定字符串加签再用支付宝公钥对应用公钥做校验。SDK初始化时alipayPublicKey参数填的必须是开放平台“应用详情—开发设置—接口加签方式”里展示的支付宝公钥不是你上传的那个应用公钥。区分不了这两个后面所有接口都跑不通。2.3 引入SDK并写出一个可靠的AlipayClient配置类Maven依赖里使用com.alipay.sdk:alipay-sdk-java版本用4.x即可具体版本号以Maven Central为准。SDK本身是黑匣子但初始化方式很固定通过DefaultAlipayClient创建客户端所有请求都由它发出。Configuration ConfigurationProperties(prefix alipay) public class AlipayConfig { private String appId; private String privateKey; private String alipayPublicKey; private String serverUrl; private String notifyUrl; private String signType RSA2; Bean public AlipayClient alipayClient() { return new DefaultAlipayClient( serverUrl, appId, privateKey, json, UTF-8, alipayPublicKey, signType ); } // getter 和 setter 省略 }这段代码的逻辑很清楚serverUrl决定了请求打到真实环境还是沙箱appId对应开放平台创建的应用privateKey是应用私钥alipayPublicKey是支付宝公钥signType固定RSA2。DefaultAlipayClient初始化时不会联网配置错误只会在第一次调用接口时显现。在application.yml里对应写入alipay: server-url: https://openapi.alipaydev.com/gateway.do app-id: 2021000123456789 private-key: MIIEvQIBADANBg... alipay-public-key: MIIBIjANBg... notify-url: https://api.example.com/alipay/notify sign-type: RSA2notifyUrl必须是可以被公网访问的地址回调时支付宝只认这个配置。沙箱环境同样要求公网可达本地开发阶段可以用内网穿透工具把本机映射出去。启动项目前先确认这些参数都能从环境变量读取不要把私钥提交到Git仓库这是上线前必须检查的一关。3. 扫码支付两段操作预下单生成二维码异步回调更新订单3.1 选对下单接口当面付扫码 vs 电脑网站支付支付宝扫码支付在不同场景下对应不同接口。如果是线下收银用户用手机扫商家屏幕上的二维码一般走当面付的alipay.trade.precreate这个接口返回一段二维码字符串由前端渲染成二维码。如果是PC网站用户支付宝App扫码付款通常用电脑网站支付alipay.trade.page.pay它会返回一个跳转表单给浏览器。标题里的“扫码支付”在我的实践里默认按当面付的扫码支付来做因为它的集成链路更短也更容易在沙箱里完整走通。电脑网站支付的区别是下单后返回的不是二维码字符串而是一段HTML表单需要处理重定向当面付扫码返回的二维码串则可以直接交给前端qrcode库渲染对前后端都更友好。选择接口还要注意签约状态。当面付和电脑网站支付在开放平台是不同的产品需要分别签约。如果在沙箱里测试签约状态一般由沙箱环境自动开通不额外收费线上环境必须先在开放平台完成对应产品的签约否则调用接口会报“产品未开通”。3.2 预下单参数、签名与二维码返回在Service层封装一个createPayQrCode方法入参是业务订单号和支付金额。这里的金额必须是字符串单位是元支付宝不接受任何浮点数运算结果。我习惯在Service层先从数据库读取订单金额再转成字符串传给支付宝绝不使用前端传来的金额字段这样可以避免金额被篡改和浮点精度问题。Service public class AlipayScanPayService { private final AlipayClient alipayClient; private final AlipayConfig alipayConfig; public AlipayScanPayService(AlipayClient alipayClient, AlipayConfig alipayConfig) { this.alipayClient alipayClient; this.alipayConfig alipayConfig; } public String createQrCode(String outTradeNo, String totalAmount, String subject) throws AlipayApiException { AlipayTradePrecreateRequest request new AlipayTradePrecreateRequest(); request.setNotifyUrl(alipayConfig.getNotifyUrl()); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, outTradeNo); bizContent.put(total_amount, totalAmount); bizContent.put(subject, subject); // 超时时间单位为分钟建议使用动态值 bizContent.put(timeout_express, 15m); request.setBizContent(bizContent.toJSONString()); AlipayTradePrecreateResponse response alipayClient.execute(request); if (!response.isSuccess()) { throw new RuntimeException(支付宝下单失败 response.getSubMsg()); } return response.getQrCode(); } }这段代码的关键参数解释out_trade_no是商户订单号必须全局唯一重复下单会被支付宝拒绝total_amount是订单金额精确到分比如0.01表示一分钱subject会显示在用户账单里timeout_express设置订单过期时间我一般设置15分钟用户扫码后超过这个时间未支付支付宝会自动关闭避免僵尸订单占用库里的订单状态。接口返回的response.getQrCode()是一串文本形式的二维码内容不是图片。前端拿到后用JavaScript库画到页面或打印成小票二维码里包含的是支付宝的支付短链接。这一步做完扫码支付的“下单”部分就结束了剩下的是被动等支付宝回调。3.3 异步回调验签、金额比对、幂等更新支付宝扫码支付成功后会以POST表单形式异步访问notifyUrl参数是平铺的Map。Controller 接收到请求后必须第一时间验签验签通过才能处理业务数据。PostMapping(/alipay/notify) public String handleNotify(RequestParam MapString, String params) throws AlipayApiException { // 1. 验签防止伪造回调 boolean signPass AlipaySignature.rsaCheckV1( params, alipayConfig.getAlipayPublicKey(), UTF-8, alipayConfig.getSignType() ); if (!signPass) { return failure; } // 2. 业务校验 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); // 这里从数据库取订单比较 totalAmount 是否一致 Order order orderService.getByOutTradeNo(outTradeNo); if (order null) { return failure; } if (!new BigDecimal(order.getAmount()).equals(new BigDecimal(totalAmount))) { return failure; } // 3. 幂等更新只有待支付状态才更新 if ((TRADE_SUCCESS.equals(tradeStatus) || TRADE_FINISHED.equals(tradeStatus)) WAIT_PAY.equals(order.getStatus())) { orderService.markPaid(outTradeNo, tradeNo); } // 4. 必须返回 success 纯文本 return success; }逻辑说明rsaCheckV1内部会用支付宝公钥对参数签名做验证它要求传入的Map里包含原始的sign字段SDK会自己剔除。第二步业务校验最重要线上收到的回调可能是伪造的即使验签通过也必须比对金额和订单号。第三步用状态条件实现幂等支付宝在支付成功后可能会多次通知同一个结果重复执行会导致状态覆盖或重复发货所以必须要求当前订单是“待支付”状态才更新。参数解释trade_no是支付宝交易号它会跟随这笔订单终身生效退款、对账都会用到所以要存入订单表。trade_status在TRADE_SUCCESS时表示支付成功TRADE_FINISHED表示支付完成且退款额度已用完两种状态对你来说都算已支付。如果代码里没做幂等可以用一张pay_notify_log表记录支付宝交易号再配合唯一索引比单纯依赖状态判断更稳。4. 支付宝扫码支付接入避坑五个让订单对不上的问题4.1 私钥与签名相关的“玄学”报错现象沙箱里下单立刻报“签名验证失败”或者收到回调后rsaCheckV1一直返回false。原因最常见的是把应用公钥当支付宝公钥使用还有私钥没有用PKCS8格式以及YAML里private-key用了双引号导致换行转义错误。解决回到开放平台开发设置里重新复制支付宝公钥注意是一整串MIIB...开头的字符。Java代码里直接用PKCS8私钥字符串并在YAML中加单引号。如果已经生成了PKCS1格式私钥用工具转换成PKCS8再贴过来。我用过最稳妥的办法是把私钥放到环境变量而不是YAML里启动时通过Value注入既避免换行问题也避免误提交。4.2 下单成功但二维码扫不出来现象前端把response.getQrCode()当成了普通字符串放入二维码生成库扫出来是一个网页但页面提示“无法验证应用”或直接白屏。原因有些前端实现会把二维码内容再次编码或使用了不兼容的渲染组件。支付宝二维码内容本身是支付链接不需要前端二次加工。解决前端用qrcode库直接渲染字符串图片尺寸不要小于200x200确保用户能用支付宝扫。如果页面是PC端可以增加“保存二维码”按钮如果用户用的是微信扫一扫会提示无法识别这属于正常现象并不是支付服务的问题。二维码有效期受timeout_express控制过期后扫出来提示订单关闭需要回到下单页重新生成。4.3 沙箱支付后收不到回调现象用沙箱钱包扫码付款成功本地项目日志里完全没有/alipay/notify的访问记录。原因支付宝回调要求notify_url能公网访问。本地开发localhost地址支付宝访问不到很多人以为配置了沙箱环境就可以回调到本地这是没弄明白回调链路。解决本地开发可以用内网穿透工具把本机端口映射成公网地址然后把该地址填到notify_url。注意穿透工具的免费域名不稳定如果项目在服务器上直接把notify_url指向一个测试环境的域名。回调地址后面不要带query参数支付宝会在notify_url后拼接自己的参数如果地址本身带参数容易出问题。4.4 重复回调造成订单状态错乱现象同一个订单支付宝回调了三次数据库里订单从“已支付”被改成了“退款中”或者发货逻辑被执行多次。原因支付宝的异步通知为了可靠性会重复发送间隔时间递增直到应用返回success。如果业务处理写得不幂等重复通知就会带来脏更新。解决在更新订单的SQL里带上状态条件例如update order set status PAID where out_trade_no ? and status WAIT_PAY。同时维护一张回调通知表记录trade_no和本次回调的参数摘要用trade_no加唯一索引第一次插入成功才继续业务逻辑后面重复插入直接跳过。如果订单存在退款逻辑状态机要设计成单向流转避免把已支付状态又改回待支付。4.5 金额比对把单位搞混现象用户支付0.01元数据库订单金额是0.01但回调里total_amount是1.00比对不通过导致回调失败。原因支付宝回调金额单位是元字符串形式。有些开发把数据库金额存成“分”或者前端把金额转成了Double结果0.01变成了0.010000000000000000208。解决下单和回调比对统一以“元”为单位用BigDecimal比较不要用equals因为字符串0.01和0.010在BigDecimal里相等性判断也依赖精度。更稳妥的做法是数据库保存金额单位是“分”在传给支付宝时转换为“元”字符串回调时再把total_amount乘以100转为“分”来比对。我自己的项目里统一用的是BigDecimal并设置为两位小数避免任何浮点运算。5. 从扫码支付到刷脸支付官方奖励政策的获取路径与Java侧改动5.1 刷脸支付不是另一套支付体系只是换了收款交互很多Java后端一听到“支付宝刷脸支付”就以为是新SDK、新协议实际上刷脸支付的资金链路依然是支付宝交易接口刷脸设备帮你完成了原本需要用户扫码的那一步。后端处理的核心逻辑还是预下单、异步回调、验签、更新订单。换句话说你把扫码支付集成好后刷脸支付的服务端改动没有想象中那么大。区别体验在设备端扫码支付是用户手机主动扫商家二维码刷脸支付是用户在蜻蜓等设备上确认刷脸。设备会调用支付宝开放能力最终仍然由支付宝向业务系统的notify_url发起支付结果通知。所以回调验签、订单幂等、对账脚本这些代码直接从扫码支付项目里复用过来即可不需要重写。5.2 官方奖励政策怎么查、怎么核对“支付宝刷脸支付官方奖励政策”经常出现在服务商和商家的讨论里它的核心是服务商或商户在指定时间内推广刷脸设备、产生有效交易支付宝会给予一定比例或固定金额的奖励。这类政策是阶段性活动会调整不存在一个固定不变的奖励标准所以任何文章或截图告诉你“刷脸一台返xxx元”都需要警惕。获取官方信息只能看三个渠道支付宝开放平台官网的公告中心、服务商后台的运营活动模块以及与你签约的支付宝业务经理提供的合同文档。开放平台域名是open.alipay.com不要点陌生短信里的“刷脸奖励领取”链接。核对政策时要关注这几个字段适用设备型号、活动开始和结束时间、有效交易定义、奖励核算周期、结算方式。开发侧没必要深入研究每一条但要把订单表里的支付设备类型和交易时间保留好作为后续核算的数据来源。5.3 服务端要提前准备的三个改动如果你计划在扫码支付项目里扩展刷脸支付我建议先把下面三件事做了。第一订单表增加device_id和pay_type字段刷脸支付回调里会带上设备号你可以在回调验签后把它存下来第二配置一个新的notify_url给刷脸设备产品使用方便在日志里按来源区分设备避免和扫码支付的通知混在一起第三在开放平台单独申请刷脸支付相关的产品权限扫码支付签约并不代表刷脸支付自动开通。// 在回调参数中读取设备号用于统计设备有效交易 String deviceId params.get(device_id); if (StringUtils.hasText(deviceId)) { orderService.updateDeviceId(outTradeNo, deviceId); }这段代码放在验签和金额校验之后更新订单状态之前。device_id是支付宝返回的设备唯一标识刷脸支付政策里的“有效动账”统计会依赖它。提前把这些字段存下来后续即使奖励政策调整也能在后台导出交易明细进行核对而不是等到需要统计时才发现日志里没有设备维度。另外沙箱环境通常不提供真实的刷脸设备测试时可以用开放平台提供的刷脸Stub工具或联系业务经理开通测试设备。不要自行下载非官方刷脸App避免账号风险。6. 上线前必须做的验证主动查单与对账兜底扫码支付集成完毕后不能只在沙箱里付款成功就算结束。我的习惯是在上线前把“主动查单”加上因为支付宝回调不是百分之百即时到达网络抖动或服务器重启都可能造成通知丢失。主动查单的逻辑很简单对本地“待支付”订单启动定时任务每5分钟调用一次alipay.trade.query接口如果返回TRADE_SUCCESS就手动执行和回调一样的订单更新逻辑。Scheduled(fixedDelay 300000) public void handleTimeoutOrders() { ListOrder waitPayOrders orderService.listWaitPay(); for (Order order : waitPayOrders) { AlipayTradeQueryRequest request new AlipayTradeQueryRequest(); request.setBizContent({\out_trade_no\:\ order.getOrderNo() \}); AlipayTradeQueryResponse response alipayClient.execute(request); if (TRADE_SUCCESS.equals(response.getTradeStatus())) { orderService.markPaid(order.getOrderNo(), response.getTradeNo()); } } }这段代码里用到定时任务主启动类上需要加EnableScheduling。查询接口没有回调那么多校验但仍要判断trade_status和金额。把主动查单和回调更新放在同一个事务方法里执行保证重复通知时两个途径最终结果一致。另一个有用的验证方法是对账单支付宝开放平台会提供按日汇总的账单文件可以下载下来和本地订单表做比对。对账金额一致说明这条支付链路已经稳定了不一致再进订单日志排查。我第一次接支付时只做了回调上线第二天就发现红冲订单没处理后面补了对账脚本才真正安心。现在每个项目我都会先做主动查单再做对账这让我少熬了很多夜。希望帮到你。本文还有配套的精品资源点击获取