简介这是一套面向Java开发者的支付宝扫码支付集成实战项目适合电商、O2O等场景下需要快速接入支付能力的初中级工程师参考学习。项目围绕支付宝SDK展开涵盖扫码支付全流程包括二维码生成与解析、支付请求发起、异步回调处理、订单状态同步等核心环节并配有前端展示页面用于呈现动态二维码与支付状态。资源包共124个文件约27.64MB以jar依赖库、java源码、class编译文件、xml配置、js脚本及properties参数文件为主其中zfbinfo.properties用于集中管理appid与密钥等安全凭证示例代码则演示了SDK调用与回调处理的关键步骤。目前已有2483人学习。通过研读源码与配置读者可掌握支付接口调用规范、密钥管理、数据加密及防注入等安全实践并理解前后端交互与异常场景的测试调试思路为实际项目落地提供可复用的参考方案。1. 扫码支付接入这件事为什么我建议先跑通这份 Java 项目再谈刷脸去年帮一个做社区团购的朋友排查支付问题他的技术负责人拍胸脯说支付宝扫码支付早就接完了结果上线三天订单状态和支付宝账单对不上财务那边每天手工核账到凌晨。翻代码一看回调验签用的是明文比对异步通知没做幂等二维码超时时间写死在页面里。这类问题不是 SDK 不会用而是整条链路没跑通过一遍。这份 Java 集成支付宝扫码支付项目价值就在这儿它把 AlipayFaceToFaceController、AlipayFaceToFace、ZFBFaceToFaceModel 这几个核心类加上 zfbinfo.properties 配置和前端二维码展示页凑成了一条能从头走到尾的最小闭环。你拿到手不是一堆散装 API 文档而是一个能直接跑起来、能看到二维码、能收到回调的工程骨架。适合谁正在做电商、O2O、自助收银的 Java 后端尤其是第一次接支付宝、或者接过但被回调坑过的人。刷脸支付官方奖励政策那部分本质是支付宝对服务商的返佣规则跟技术接入是两条线但项目里预留的刷脸入口值得一并看。2. 拆开这个工程核心类、配置文件和二维码链路到底怎么串2.1 从 class 文件反推工程结构项目正文里列出的文件很有意思全是 .classAlipayFaceToFaceController、AlipayFaceToFace、ZFBFaceToFaceModel、TestController、CommonUtils。这说明拿到的是一份编译产物不是源码工程。对一线开发来说这反而是个信号——你得先搞清楚每个类大概承担什么职责再决定是反编译看逻辑还是直接照着重写。按支付宝当面付的通用分层这几个类大概率是这样分工的类名推测职责对应支付宝能力AlipayFaceToFaceControllerHTTP 入口接收下单请求、返回二维码统一下单 alipay.trade.precreateAlipayFaceToFace封装 SDK 调用、组装请求参数AlipayClient 执行ZFBFaceToFaceModel请求/响应数据模型订单号、金额、subjectTestController本地联调入口模拟下单、查单CommonUtils签名、配置读取工具验签、properties 加载Controller 层负责把前端传来的金额、订单号转成 SDK 需要的 BizContentService 层这里可能是 AlipayFaceToFace调 AlipayClient.execute拿到 qr_code 字段返回给前端渲染成二维码。用户扫码付款后支付宝异步 POST 到你的 notify_urlController 再验签、改订单状态。整条链路就三件事下单拿码、展示、回调改状态。2.2 zfbinfo.properties 里到底该放什么配置是这个项目最容易翻车的地方。zfbinfo.properties 通常长这样# 支付宝网关沙箱和正式环境不同 gatewayUrlhttps://openapi.alipay.com/gateway.do # 应用唯一标识开放平台创建应用后分配 app_id2021000000000000 # 应用私钥PKCS8 格式一行到底不要换行 merchant_private_keyMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQ... # 支付宝公钥用于验签回调注意不是应用公钥 alipay_public_keyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA... # 异步通知地址必须是公网可访问的 http/https notify_urlhttps://your-domain.com/alipay/notify # 同步跳转地址 return_urlhttps://your-domain.com/alipay/return # 签名类型 sign_typeRSA2 # 字符编码 charsetUTF-8这里有个血泪经验merchant_private_key 是应用私钥alipay_public_key 是支付宝公钥两个完全不同的东西。很多人把应用公钥填到 alipay_public_key 里下单能成功回调验签必失败因为验签用的是支付宝的公钥。还有私钥格式Java 用的是 PKCS8不是 PKCS1用工具生成时选错格式启动就报 InvalidKeyException。2.3 下单拿二维码的最小可运行代码假设你已经把 SDK 依赖加进 pomdependency groupIdcom.alipay.sdk/groupId artifactIdalipay-sdk-java/artifactId version4.38.0.ALL/version /dependency下单逻辑核心就这几行// 初始化 AlipayClient全局单例即可不要每次请求都 new AlipayClient alipayClient new DefaultAlipayClient( gatewayUrl, appId, merchantPrivateKey, json, charset, alipayPublicKey, signType); // 组装请求 AlipayTradePrecreateRequest request new AlipayTradePrecreateRequest(); request.setNotifyUrl(notifyUrl); AlipayTradePrecreateModel model new AlipayTradePrecreateModel(); model.setOutTradeNo(ORDER_ System.currentTimeMillis()); // 商户订单号全局唯一 model.setTotalAmount(0.01); // 金额字符串单位元两位小数 model.setSubject(测试商品); // 订单标题 model.setTimeoutExpress(30m); // 二维码30分钟过期不设默认2小时 request.setBizContent(JSON.toJSONString(model)); // 执行 AlipayTradePrecreateResponse response alipayClient.execute(request); if (response.isSuccess()) { String qrCode response.getQrCode(); // 前端拿这个生成二维码 } else { // 失败看 subCode 和 subMsg别只看 msg log.error(下单失败 code{} subCode{} subMsg{}, response.getCode(), response.getSubCode(), response.getSubMsg()); }参数说明几个关键点out_trade_no 必须全局唯一重复会报 ACQ.TRADE_HAS_SUCCESStotal_amount 是字符串不是 double用 double 会有精度问题timeout_express 不设默认 2 小时自助收银场景建议 5 到 30 分钟避免用户扫了旧码。execute 返回的 response 里isSuccess 判断的是 code 等于 10000业务失败要看 subCode比如 ACQ.SYSTEM_ERROR 是系统异常可重试ACQ.INVALID_PARAMETER 是参数问题别重试。2.4 前端二维码展示与轮询后端返回 qr_code 字符串后前端用 qrcode.js 之类生成图片// 用 qrcodejs 把后端返回的 qr_code 渲染成二维码 new QRCode(document.getElementById(qrcode), { text: qrCode, // 后端返回的支付链接 width: 220, height: 220, correctLevel: QRCode.CorrectLevel.M }); // 轮询订单状态3秒一次最多查60次 let count 0; const timer setInterval(async () { const res await fetch(/alipay/query?outTradeNo${outTradeNo}); const data await res.json(); if (data.status TRADE_SUCCESS) { clearInterval(timer); location.href /pay/success; } if (count 60) clearInterval(timer); // 超时停止 }, 3000);轮询是兜底手段真正可靠的还是异步回调。轮询间隔别太短3 秒够用太频繁会给服务器压力。查询接口内部调的是 alipay.trade.query返回 trade_status 为 TRADE_SUCCESS 才算成功WAIT_BUYER_PAY 是待支付。3. 异步回调处理验签、幂等、状态机一个都不能少3.1 回调验签的正确姿势异步通知是支付链路里最关键的环节也是最容易出问题的地方。支付宝 POST 过来的参数是一堆 form 字段验签必须用支付宝公钥RequestMapping(value /alipay/notify, method RequestMethod.POST) public String notify(HttpServletRequest request) { MapString, String params new HashMap(); request.getParameterMap().forEach((k, v) - params.put(k, v[0])); // 验签用支付宝公钥不是应用公钥 boolean signVerified AlipaySignature.rsaCheckV1( params, alipayPublicKey, UTF-8, RSA2); if (!signVerified) { log.warn(验签失败可能是伪造请求); return failure; } String tradeStatus params.get(trade_status); String outTradeNo params.get(out_trade_no); String tradeNo params.get(trade_no); // 支付宝交易号 if (TRADE_SUCCESS.equals(tradeStatus)) { // 幂等处理见下一节 handleSuccess(outTradeNo, tradeNo, params.get(total_amount)); } return success; // 必须返回纯字符串 success否则支付宝会重试 }注意几个细节rsaCheckV1 的 charset 和 signType 必须和配置一致返回给支付宝的必须是纯文本 success返回 JSON 或者带引号都会被判定为失败然后支付宝按 4m、10m、10m、1h、2h、6h、15h 的频率重试最多 8 次。验签失败直接返回 failure别继续处理业务。3.2 幂等同一笔回调可能来八次支付宝回调是 at-least-once同一笔订单可能通知多次。如果不做幂等库存扣两次、积分加两次财务对账就崩了。常见做法是用订单号加唯一索引或者用 Redis 分布式锁public void handleSuccess(String outTradeNo, String tradeNo, String amount) { // 数据库层面update order set statusPAID where out_trade_no? and statusUNPAID // 返回影响行数为0说明已经处理过直接返回 int rows orderMapper.updateToPaid(outTradeNo, tradeNo, amount); if (rows 0) { log.info(订单{}已处理忽略重复回调, outTradeNo); return; } // 只有真正更新成功才做后续扣库存、发消息 inventoryService.deduct(outTradeNo); mqProducer.sendPaidEvent(outTradeNo); }用 update 的影响行数做幂等是最省事的方案比先 select 再 update 可靠因为 update 带 status 条件是原子的。如果业务复杂可以在 Redis 里 setnx 一个 key过期时间设 24 小时但要注意 Redis 和数据库的一致性别锁成功了数据库没更新。3.3 订单状态机别写成一锅粥支付订单的状态流转要清晰待支付、已支付、已关闭、已退款。回调只负责把待支付改成已支付其他状态变更走各自的接口。我见过把退款逻辑也塞进回调里的结果用户退款后支付宝又推了一次支付成功通知订单状态来回跳。状态机建议用枚举加校验public enum OrderStatus { UNPAID, PAID, CLOSED, REFUNDED; } // 状态流转校验 public boolean canTransfer(OrderStatus from, OrderStatus to) { if (from UNPAID to PAID) return true; if (from UNPAID to CLOSED) return true; if (from PAID to REFUNDED) return true; return false; }回调里先查当前状态只有 UNPAID 才处理其他状态直接返回 success 让支付宝停止重试。这样即使有异常通知也不会把已退款的订单改回已支付。3.4 主动查单作为兜底回调可能因为网络问题丢失所以生产环境一定要有主动查单。常见做法是定时任务扫描 5 分钟前创建且状态还是 UNPAID 的订单调 alipay.trade.query 查真实状态// 定时任务每分钟跑一次 Scheduled(cron 0 * * * * ?) public void reconcile() { ListOrder orders orderMapper.selectUnpaidBefore( LocalDateTime.now().minusMinutes(5)); for (Order order : orders) { AlipayTradeQueryResponse resp alipayClient.execute( new AlipayTradeQueryRequest() {{ setBizContent({\out_trade_no\:\ order.getOutTradeNo() \}); }}); if (resp.isSuccess() TRADE_SUCCESS.equals(resp.getTradeStatus())) { handleSuccess(order.getOutTradeNo(), resp.getTradeNo(), resp.getTotalAmount()); } } }查单和回调走同一个 handleSuccess保证幂等逻辑复用。查单频率别太高支付宝有调用量限制一般订单量下每分钟一次够用。4. 避坑排查回调、密钥、二维码这几个地方最容易翻车4.1 回调一直重试日志里全是验签失败现象支付宝后台显示通知失败服务器日志里 rsaCheckV1 返回 false但下单是成功的。原因alipay_public_key 填成了应用公钥。应用公钥是你自己生成的用来让支付宝验证你的请求支付宝公钥是支付宝给你的用来让你验证支付宝的回调。两者搞反下单能成因为用的是你的私钥签名回调必失败。解决登录开放平台在应用详情里找到支付宝公钥复制完整内容替换配置。注意公钥是一整行中间不能有换行和空格复制时容易带上换行符用代码 trim 一下。4.2 二维码扫出来提示订单不存在或已失效现象用户扫码后支付宝提示订单失效但下单接口返回是成功的。原因out_trade_no 重复了。如果订单号生成规则是时间戳高并发下同一毫秒可能生成相同订单号支付宝侧第一笔已创建第二笔就报重复。或者 timeout_express 设得太短用户还没扫就过期了。解决订单号用业务前缀 日期 序列号或者雪花算法保证全局唯一。timeout_express 根据场景设自助收银 5 分钟电商 30 分钟别用默认值。4.3 回调返回了 success 但支付宝还在重试现象代码里明明 return success支付宝后台还是显示通知失败。原因Controller 上加了 ResponseBody 或者 RestControllerSpring 把 success 当字符串序列化成了 success带了引号。支付宝只认纯文本 success。解决回调方法用 Controller 加 ResponseBody或者直接往 response 里写response.setContentType(text/plain;charsetUTF-8); response.getWriter().write(success); response.getWriter().flush();别用 RestController 返回 String除非你确认序列化配置不会加引号。4.4 沙箱环境能跑正式环境报无权限现象沙箱里下单、回调都正常切到正式环境报 ACQ.INVALID_PARAMETER 或者无权限。原因正式环境的 app_id 和密钥跟沙箱不是一套gatewayUrl 也要从 sandbox 换成正式地址。另外正式环境需要签约当面付产品没签约就调接口会报无权限。解决检查 gatewayUrl 是否为 https://openapi.alipay.com/gateway.doapp_id 和密钥是否换成正式环境的开放平台产品中心确认当面付已签约生效。4.5 金额对不上差几分钱现象订单金额 0.01 元支付宝回调里的 total_amount 是 0.01但数据库存的是 1。原因单位搞混了。支付宝接口的 total_amount 单位是元字符串格式有些内部系统用分做单位转换时乘了 100 又没除回来。解决统一在边界层转换接口层用元内部存储用分转换函数只写一处别到处乘除。金额计算用 BigDecimal别用 double。5. 从扫码到刷脸奖励政策背后的技术衔接与验证习惯刷脸支付官方奖励政策本质是支付宝对铺设刷脸设备的服务商按笔返佣跟扫码支付是同一套商户体系下的两种收单方式。技术上刷脸走的是 alipay.trade.pay 接口传 auth_code用户刷脸后设备返回的付款码而不是 precreate 生成二维码。项目里如果预留了刷脸入口大概率是在 AlipayFaceToFace 里加了一个分支根据支付方式调不同接口。从扫码切到刷脸代码改动集中在三处下单接口从 precreate 换成 pay参数从 total_amount 加 subject 换成 auth_code 加 scene回调处理逻辑完全复用。所以先把扫码链路跑通刷脸就是换个接口的事。奖励政策那部分服务商需要在开放平台报备设备返佣按日结算跟技术接入不冲突但设备激活状态会影响返佣调试时别用未报备的设备测。验证支付链路我一般强制走一遍这四步步骤操作预期结果1沙箱下单用沙箱版支付宝扫码支付成功回调收到订单变 PAID2手动重复推送同一笔回调第二次返回 success订单状态不变3关掉回调接口下单后主动查单定时任务把订单改成 PAID4用错误公钥验签验签失败返回 failure订单不变这四步能覆盖验签、幂等、兜底、安全四个维度。我见过太多人只测第一步上线后回调丢了、重复了、被伪造了全是血泪。还有个习惯每次改完支付相关代码我都会把 zfbinfo.properties 里的 notify_url 指向本地 ngrok 或者内网穿透地址用真实支付宝扫一笔 0.01 元。沙箱和正式环境的差异只有真金白银跑一遍才暴露得出来。从那以后我每次上线支付功能都强制走一遍真实小额支付加回调日志核对再急也不跳过。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/9/28 12:52:20 · 阅读 1.2k Java集成支付宝扫码支付实战：从下单到回调的完整链路与避坑指南
简介这是一套面向Java开发者的支付宝扫码支付集成实战项目适合电商、O2O等场景下需要快速接入支付能力的初中级工程师参考学习。项目围绕支付宝SDK展开涵盖扫码支付全流程包括二维码生成与解析、支付请求发起、异步回调处理、订单状态同步等核心环节并配有前端展示页面用于呈现动态二维码与支付状态。资源包共124个文件约27.64MB以jar依赖库、java源码、class编译文件、xml配置、js脚本及properties参数文件为主其中zfbinfo.properties用于集中管理appid与密钥等安全凭证示例代码则演示了SDK调用与回调处理的关键步骤。目前已有2483人学习。通过研读源码与配置读者可掌握支付接口调用规范、密钥管理、数据加密及防注入等安全实践并理解前后端交互与异常场景的测试调试思路为实际项目落地提供可复用的参考方案。1. 扫码支付接入这件事为什么我建议先跑通这份 Java 项目再谈刷脸去年帮一个做社区团购的朋友排查支付问题他的技术负责人拍胸脯说支付宝扫码支付早就接完了结果上线三天订单状态和支付宝账单对不上财务那边每天手工核账到凌晨。翻代码一看回调验签用的是明文比对异步通知没做幂等二维码超时时间写死在页面里。这类问题不是 SDK 不会用而是整条链路没跑通过一遍。这份 Java 集成支付宝扫码支付项目价值就在这儿它把 AlipayFaceToFaceController、AlipayFaceToFace、ZFBFaceToFaceModel 这几个核心类加上 zfbinfo.properties 配置和前端二维码展示页凑成了一条能从头走到尾的最小闭环。你拿到手不是一堆散装 API 文档而是一个能直接跑起来、能看到二维码、能收到回调的工程骨架。适合谁正在做电商、O2O、自助收银的 Java 后端尤其是第一次接支付宝、或者接过但被回调坑过的人。刷脸支付官方奖励政策那部分本质是支付宝对服务商的返佣规则跟技术接入是两条线但项目里预留的刷脸入口值得一并看。2. 拆开这个工程核心类、配置文件和二维码链路到底怎么串2.1 从 class 文件反推工程结构项目正文里列出的文件很有意思全是 .classAlipayFaceToFaceController、AlipayFaceToFace、ZFBFaceToFaceModel、TestController、CommonUtils。这说明拿到的是一份编译产物不是源码工程。对一线开发来说这反而是个信号——你得先搞清楚每个类大概承担什么职责再决定是反编译看逻辑还是直接照着重写。按支付宝当面付的通用分层这几个类大概率是这样分工的类名推测职责对应支付宝能力AlipayFaceToFaceControllerHTTP 入口接收下单请求、返回二维码统一下单 alipay.trade.precreateAlipayFaceToFace封装 SDK 调用、组装请求参数AlipayClient 执行ZFBFaceToFaceModel请求/响应数据模型订单号、金额、subjectTestController本地联调入口模拟下单、查单CommonUtils签名、配置读取工具验签、properties 加载Controller 层负责把前端传来的金额、订单号转成 SDK 需要的 BizContentService 层这里可能是 AlipayFaceToFace调 AlipayClient.execute拿到 qr_code 字段返回给前端渲染成二维码。用户扫码付款后支付宝异步 POST 到你的 notify_urlController 再验签、改订单状态。整条链路就三件事下单拿码、展示、回调改状态。2.2 zfbinfo.properties 里到底该放什么配置是这个项目最容易翻车的地方。zfbinfo.properties 通常长这样# 支付宝网关沙箱和正式环境不同 gatewayUrlhttps://openapi.alipay.com/gateway.do # 应用唯一标识开放平台创建应用后分配 app_id2021000000000000 # 应用私钥PKCS8 格式一行到底不要换行 merchant_private_keyMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQ... # 支付宝公钥用于验签回调注意不是应用公钥 alipay_public_keyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA... # 异步通知地址必须是公网可访问的 http/https notify_urlhttps://your-domain.com/alipay/notify # 同步跳转地址 return_urlhttps://your-domain.com/alipay/return # 签名类型 sign_typeRSA2 # 字符编码 charsetUTF-8这里有个血泪经验merchant_private_key 是应用私钥alipay_public_key 是支付宝公钥两个完全不同的东西。很多人把应用公钥填到 alipay_public_key 里下单能成功回调验签必失败因为验签用的是支付宝的公钥。还有私钥格式Java 用的是 PKCS8不是 PKCS1用工具生成时选错格式启动就报 InvalidKeyException。2.3 下单拿二维码的最小可运行代码假设你已经把 SDK 依赖加进 pomdependency groupIdcom.alipay.sdk/groupId artifactIdalipay-sdk-java/artifactId version4.38.0.ALL/version /dependency下单逻辑核心就这几行// 初始化 AlipayClient全局单例即可不要每次请求都 new AlipayClient alipayClient new DefaultAlipayClient( gatewayUrl, appId, merchantPrivateKey, json, charset, alipayPublicKey, signType); // 组装请求 AlipayTradePrecreateRequest request new AlipayTradePrecreateRequest(); request.setNotifyUrl(notifyUrl); AlipayTradePrecreateModel model new AlipayTradePrecreateModel(); model.setOutTradeNo(ORDER_ System.currentTimeMillis()); // 商户订单号全局唯一 model.setTotalAmount(0.01); // 金额字符串单位元两位小数 model.setSubject(测试商品); // 订单标题 model.setTimeoutExpress(30m); // 二维码30分钟过期不设默认2小时 request.setBizContent(JSON.toJSONString(model)); // 执行 AlipayTradePrecreateResponse response alipayClient.execute(request); if (response.isSuccess()) { String qrCode response.getQrCode(); // 前端拿这个生成二维码 } else { // 失败看 subCode 和 subMsg别只看 msg log.error(下单失败 code{} subCode{} subMsg{}, response.getCode(), response.getSubCode(), response.getSubMsg()); }参数说明几个关键点out_trade_no 必须全局唯一重复会报 ACQ.TRADE_HAS_SUCCESStotal_amount 是字符串不是 double用 double 会有精度问题timeout_express 不设默认 2 小时自助收银场景建议 5 到 30 分钟避免用户扫了旧码。execute 返回的 response 里isSuccess 判断的是 code 等于 10000业务失败要看 subCode比如 ACQ.SYSTEM_ERROR 是系统异常可重试ACQ.INVALID_PARAMETER 是参数问题别重试。2.4 前端二维码展示与轮询后端返回 qr_code 字符串后前端用 qrcode.js 之类生成图片// 用 qrcodejs 把后端返回的 qr_code 渲染成二维码 new QRCode(document.getElementById(qrcode), { text: qrCode, // 后端返回的支付链接 width: 220, height: 220, correctLevel: QRCode.CorrectLevel.M }); // 轮询订单状态3秒一次最多查60次 let count 0; const timer setInterval(async () { const res await fetch(/alipay/query?outTradeNo${outTradeNo}); const data await res.json(); if (data.status TRADE_SUCCESS) { clearInterval(timer); location.href /pay/success; } if (count 60) clearInterval(timer); // 超时停止 }, 3000);轮询是兜底手段真正可靠的还是异步回调。轮询间隔别太短3 秒够用太频繁会给服务器压力。查询接口内部调的是 alipay.trade.query返回 trade_status 为 TRADE_SUCCESS 才算成功WAIT_BUYER_PAY 是待支付。3. 异步回调处理验签、幂等、状态机一个都不能少3.1 回调验签的正确姿势异步通知是支付链路里最关键的环节也是最容易出问题的地方。支付宝 POST 过来的参数是一堆 form 字段验签必须用支付宝公钥RequestMapping(value /alipay/notify, method RequestMethod.POST) public String notify(HttpServletRequest request) { MapString, String params new HashMap(); request.getParameterMap().forEach((k, v) - params.put(k, v[0])); // 验签用支付宝公钥不是应用公钥 boolean signVerified AlipaySignature.rsaCheckV1( params, alipayPublicKey, UTF-8, RSA2); if (!signVerified) { log.warn(验签失败可能是伪造请求); return failure; } String tradeStatus params.get(trade_status); String outTradeNo params.get(out_trade_no); String tradeNo params.get(trade_no); // 支付宝交易号 if (TRADE_SUCCESS.equals(tradeStatus)) { // 幂等处理见下一节 handleSuccess(outTradeNo, tradeNo, params.get(total_amount)); } return success; // 必须返回纯字符串 success否则支付宝会重试 }注意几个细节rsaCheckV1 的 charset 和 signType 必须和配置一致返回给支付宝的必须是纯文本 success返回 JSON 或者带引号都会被判定为失败然后支付宝按 4m、10m、10m、1h、2h、6h、15h 的频率重试最多 8 次。验签失败直接返回 failure别继续处理业务。3.2 幂等同一笔回调可能来八次支付宝回调是 at-least-once同一笔订单可能通知多次。如果不做幂等库存扣两次、积分加两次财务对账就崩了。常见做法是用订单号加唯一索引或者用 Redis 分布式锁public void handleSuccess(String outTradeNo, String tradeNo, String amount) { // 数据库层面update order set statusPAID where out_trade_no? and statusUNPAID // 返回影响行数为0说明已经处理过直接返回 int rows orderMapper.updateToPaid(outTradeNo, tradeNo, amount); if (rows 0) { log.info(订单{}已处理忽略重复回调, outTradeNo); return; } // 只有真正更新成功才做后续扣库存、发消息 inventoryService.deduct(outTradeNo); mqProducer.sendPaidEvent(outTradeNo); }用 update 的影响行数做幂等是最省事的方案比先 select 再 update 可靠因为 update 带 status 条件是原子的。如果业务复杂可以在 Redis 里 setnx 一个 key过期时间设 24 小时但要注意 Redis 和数据库的一致性别锁成功了数据库没更新。3.3 订单状态机别写成一锅粥支付订单的状态流转要清晰待支付、已支付、已关闭、已退款。回调只负责把待支付改成已支付其他状态变更走各自的接口。我见过把退款逻辑也塞进回调里的结果用户退款后支付宝又推了一次支付成功通知订单状态来回跳。状态机建议用枚举加校验public enum OrderStatus { UNPAID, PAID, CLOSED, REFUNDED; } // 状态流转校验 public boolean canTransfer(OrderStatus from, OrderStatus to) { if (from UNPAID to PAID) return true; if (from UNPAID to CLOSED) return true; if (from PAID to REFUNDED) return true; return false; }回调里先查当前状态只有 UNPAID 才处理其他状态直接返回 success 让支付宝停止重试。这样即使有异常通知也不会把已退款的订单改回已支付。3.4 主动查单作为兜底回调可能因为网络问题丢失所以生产环境一定要有主动查单。常见做法是定时任务扫描 5 分钟前创建且状态还是 UNPAID 的订单调 alipay.trade.query 查真实状态// 定时任务每分钟跑一次 Scheduled(cron 0 * * * * ?) public void reconcile() { ListOrder orders orderMapper.selectUnpaidBefore( LocalDateTime.now().minusMinutes(5)); for (Order order : orders) { AlipayTradeQueryResponse resp alipayClient.execute( new AlipayTradeQueryRequest() {{ setBizContent({\out_trade_no\:\ order.getOutTradeNo() \}); }}); if (resp.isSuccess() TRADE_SUCCESS.equals(resp.getTradeStatus())) { handleSuccess(order.getOutTradeNo(), resp.getTradeNo(), resp.getTotalAmount()); } } }查单和回调走同一个 handleSuccess保证幂等逻辑复用。查单频率别太高支付宝有调用量限制一般订单量下每分钟一次够用。4. 避坑排查回调、密钥、二维码这几个地方最容易翻车4.1 回调一直重试日志里全是验签失败现象支付宝后台显示通知失败服务器日志里 rsaCheckV1 返回 false但下单是成功的。原因alipay_public_key 填成了应用公钥。应用公钥是你自己生成的用来让支付宝验证你的请求支付宝公钥是支付宝给你的用来让你验证支付宝的回调。两者搞反下单能成因为用的是你的私钥签名回调必失败。解决登录开放平台在应用详情里找到支付宝公钥复制完整内容替换配置。注意公钥是一整行中间不能有换行和空格复制时容易带上换行符用代码 trim 一下。4.2 二维码扫出来提示订单不存在或已失效现象用户扫码后支付宝提示订单失效但下单接口返回是成功的。原因out_trade_no 重复了。如果订单号生成规则是时间戳高并发下同一毫秒可能生成相同订单号支付宝侧第一笔已创建第二笔就报重复。或者 timeout_express 设得太短用户还没扫就过期了。解决订单号用业务前缀 日期 序列号或者雪花算法保证全局唯一。timeout_express 根据场景设自助收银 5 分钟电商 30 分钟别用默认值。4.3 回调返回了 success 但支付宝还在重试现象代码里明明 return success支付宝后台还是显示通知失败。原因Controller 上加了 ResponseBody 或者 RestControllerSpring 把 success 当字符串序列化成了 success带了引号。支付宝只认纯文本 success。解决回调方法用 Controller 加 ResponseBody或者直接往 response 里写response.setContentType(text/plain;charsetUTF-8); response.getWriter().write(success); response.getWriter().flush();别用 RestController 返回 String除非你确认序列化配置不会加引号。4.4 沙箱环境能跑正式环境报无权限现象沙箱里下单、回调都正常切到正式环境报 ACQ.INVALID_PARAMETER 或者无权限。原因正式环境的 app_id 和密钥跟沙箱不是一套gatewayUrl 也要从 sandbox 换成正式地址。另外正式环境需要签约当面付产品没签约就调接口会报无权限。解决检查 gatewayUrl 是否为 https://openapi.alipay.com/gateway.doapp_id 和密钥是否换成正式环境的开放平台产品中心确认当面付已签约生效。4.5 金额对不上差几分钱现象订单金额 0.01 元支付宝回调里的 total_amount 是 0.01但数据库存的是 1。原因单位搞混了。支付宝接口的 total_amount 单位是元字符串格式有些内部系统用分做单位转换时乘了 100 又没除回来。解决统一在边界层转换接口层用元内部存储用分转换函数只写一处别到处乘除。金额计算用 BigDecimal别用 double。5. 从扫码到刷脸奖励政策背后的技术衔接与验证习惯刷脸支付官方奖励政策本质是支付宝对铺设刷脸设备的服务商按笔返佣跟扫码支付是同一套商户体系下的两种收单方式。技术上刷脸走的是 alipay.trade.pay 接口传 auth_code用户刷脸后设备返回的付款码而不是 precreate 生成二维码。项目里如果预留了刷脸入口大概率是在 AlipayFaceToFace 里加了一个分支根据支付方式调不同接口。从扫码切到刷脸代码改动集中在三处下单接口从 precreate 换成 pay参数从 total_amount 加 subject 换成 auth_code 加 scene回调处理逻辑完全复用。所以先把扫码链路跑通刷脸就是换个接口的事。奖励政策那部分服务商需要在开放平台报备设备返佣按日结算跟技术接入不冲突但设备激活状态会影响返佣调试时别用未报备的设备测。验证支付链路我一般强制走一遍这四步步骤操作预期结果1沙箱下单用沙箱版支付宝扫码支付成功回调收到订单变 PAID2手动重复推送同一笔回调第二次返回 success订单状态不变3关掉回调接口下单后主动查单定时任务把订单改成 PAID4用错误公钥验签验签失败返回 failure订单不变这四步能覆盖验签、幂等、兜底、安全四个维度。我见过太多人只测第一步上线后回调丢了、重复了、被伪造了全是血泪。还有个习惯每次改完支付相关代码我都会把 zfbinfo.properties 里的 notify_url 指向本地 ngrok 或者内网穿透地址用真实支付宝扫一笔 0.01 元。沙箱和正式环境的差异只有真金白银跑一遍才暴露得出来。从那以后我每次上线支付功能都强制走一遍真实小额支付加回调日志核对再急也不跳过。希望帮到你。本文还有配套的精品资源点击获取