1. 支付接入的整体设计与核心思路拆解做过电商或者任何有交易环节的系统支付接入基本是绕不开的一关。我前后在几个项目里对接过支付宝的多种支付产品从最早的即时到账到后来的当面付、手机网站支付、APP支付踩过的坑不算少。这篇就把“Java 对接支付宝支付”这件事从头到尾拆一遍重点讲清楚设计思路、参数怎么算、代码怎么写、出问题怎么查。先说清楚这个内容适合谁看如果你是一个 Java 后端开发者手上有一个需要收钱的项目不管是 Web 网站、手机 H5、还是原生 APP需要把支付宝的支付能力接进来那这篇基本能覆盖你 80% 的场景。如果你已经接过一次但总是被回调、验签、退款这些问题卡住那这篇里的排查部分应该能帮你省不少时间。支付宝支付接入的本质其实就三件事下单、回调、对账。下单是你告诉支付宝“有这么一笔订单用户要付这么多钱”回调是支付宝告诉你“这笔钱用户付了结果是这样”对账是你自己核对“支付宝说的和我记的账对不对得上”。听起来简单但每一环都有细节尤其是签名验签和异步通知的幂等处理是新手最容易翻车的地方。1.1 为什么选支付宝开放平台而不是老接口早些年支付宝有“即时到账”这类老网关接口现在基本都迁移到支付宝开放平台OpenAPI体系下了。这个迁移不是换个地址那么简单核心变化在于老接口用的是 MD5 或 RSA 的简单签名密钥管理比较粗放开放平台统一用RSA2SHA256WithRSA签名安全性更高开放平台有统一的网关地址、统一的应用模型AppId 应用私钥 支付宝公钥支持的能力更全当面付、APP 支付、手机网站支付、电脑网站支付、小程序支付都在同一套体系里。所以现在做新项目直接上开放平台就对了别再去翻那些老文档。我见过有团队还在用老接口结果遇到退款、对账各种不兼容最后还是要重做一遍纯属浪费时间。1.2 核心概念先理清楚在动手写代码之前有几个概念必须先搞明白否则后面看文档会一头雾水。AppId你在开放平台创建应用后拿到的唯一标识相当于你的“商户身份证号”。应用私钥 / 应用公钥你自己生成的一对密钥私钥留在你服务器上用来签名公钥上传到开放平台让支付宝验证你的签名。支付宝公钥支付宝那边的一对密钥里的公钥你下载下来用来验证支付宝返回数据的签名。注意这个和你自己的应用公钥是两回事很多人第一次接会把这两个搞混。网关地址正式环境是https://openapi.alipay.com/gateway.do沙箱环境是https://openapi.alipaydev.com/gateway.do。沙箱用来测试正式上线要换成正式的。异步通知notify_url支付宝在用户支付成功后会主动 POST 一个请求到你指定的这个地址告诉你支付结果。这是你更新订单状态的主要依据。同步跳转return_url用户支付完成后浏览器跳转回的页面主要用于展示“支付成功”给用户看不能作为订单状态的依据因为用户可以伪造这个跳转。这里划重点订单状态的最终确认必须以异步通知为准同步跳转只能用来做页面展示。我见过有项目只处理同步跳转结果用户关掉页面订单就一直是待支付这就是典型的踩坑。1.3 整体流程设计一笔支付从用户点击到订单完成完整链路是这样的用户在你的系统里点击“去支付”你的后端调用支付宝的统一下单接口生成一个支付链接或支付参数用户被引导到支付宝完成付款支付宝异步 POST 通知你的notify_url你验签、核对金额、更新订单状态返回success支付宝同步跳转用户到return_url你展示支付结果页面后续通过定时对账任务拉取支付宝账单和你自己的订单做核对。这个链路里第 3 步是核心也是最容易出问题的地方。验签失败、金额对不上、重复通知、返回的不是success导致支付宝反复重推这些都是常见故障。后面我会专门用一节来讲这些问题的排查。2. 密钥、依赖与基础配置的实操要点这一节讲动手前的准备工作。别小看这些配置我见过太多项目卡在密钥格式不对、依赖版本冲突这种“低级”问题上一卡就是半天。2.1 密钥生成与格式处理支付宝官方提供了一个密钥生成工具可以生成 RSA2 密钥对。生成出来的是两个文件应用私钥和应用公钥。这里有几个细节要注意。第一私钥格式。工具生成的私钥通常是 PKCS8 格式的内容是一长串 Base64。你在代码里用的时候需要把它还原成PrivateKey对象。很多人直接把带-----BEGIN PRIVATE KEY-----头尾的字符串丢进去结果报错因为 SDK 需要的是纯 Base64 内容或者你需要自己处理头尾。第二支付宝公钥的获取。上传应用公钥后开放平台会给你一个支付宝公钥。注意如果你用的是“公钥模式”拿到的是支付宝公钥如果用的是“证书模式”那又是另一套东西。新手建议先用公钥模式简单直接。第三密钥不要硬编码在代码里。这是安全大忌。正确做法是放在配置中心或者环境变量里代码里只读配置。我见过有项目把私钥直接写在application.yml里提交到代码仓库这等于把保险箱钥匙挂在门上。下面是一个读取私钥的典型写法public static PrivateKey loadPrivateKey(String privateKeyStr) throws Exception { // 去掉头尾和换行 String content privateKeyStr .replace(-----BEGIN PRIVATE KEY-----, ) .replace(-----END PRIVATE KEY-----, ) .replaceAll(\\s, ); byte[] keyBytes Base64.getDecoder().decode(content); PKCS8EncodedKeySpec spec new PKCS8EncodedKeySpec(keyBytes); KeyFactory kf KeyFactory.getInstance(RSA); return kf.generatePrivate(spec); }这段代码的关键在于把 Base64 内容里的空白字符全部去掉否则解码会失败。这个坑我踩过当时排查了半天才发现是配置文件里换行符的问题。2.2 依赖选型官方 SDK 还是自己封装支付宝官方提供了 Java SDKMaven 坐标是com.alipay.sdk:alipay-sdk-java。我的建议是直接用官方 SDK不要自己从零封装签名和 HTTP 请求。原因很简单签名算法、参数排序、编码处理这些细节官方 SDK 都处理好了自己写容易出错官方 SDK 会跟进接口变化维护成本低出问题时社区和文档都基于官方 SDK排查方便。不过官方 SDK 也有个毛病就是版本更新比较频繁而且不同版本之间偶尔有 API 变化。建议锁定一个稳定版本不要盲目追新。我一般用比较成熟的版本比如4.x系列里经过验证的版本。如果你用的是 Spring Boot可以配合一个配置类来初始化AlipayClientConfiguration public class AlipayConfig { Value(${alipay.app-id}) private String appId; Value(${alipay.private-key}) private String privateKey; Value(${alipay.alipay-public-key}) private String alipayPublicKey; Value(${alipay.gateway-url}) private String gatewayUrl; Bean public AlipayClient alipayClient() { return new DefaultAlipayClient( gatewayUrl, appId, privateKey, json, UTF-8, alipayPublicKey, RSA2); } }注意DefaultAlipayClient的构造参数顺序网关、AppId、私钥、格式、字符集、支付宝公钥、签名类型。这个顺序记错了会直接报错而且报错信息不一定直观。2.3 沙箱环境的使用正式接入前强烈建议先在沙箱环境跑通全流程。沙箱环境有独立的 AppId、密钥和买家账号可以模拟支付、退款、查询等操作不会产生真实资金流动。沙箱的坑在于沙箱的网关地址和正式不一样密钥也是独立的不能混用。我见过有人把沙箱的密钥配到正式环境结果一直验签失败查了半天才发现是环境搞混了。所以配置里最好把沙箱和正式分开管理用 profile 或者配置中心区分。3. 下单、回调与退款的完整实现这一节是核心把下单、异步通知、退款这三个最常用的能力讲透。3.1 统一下单接口的调用支付宝的支付产品很多但下单的调用方式大同小异都是构造一个AlipayTradeXxxRequest设置业务参数然后调用alipayClient.execute()或pageExecute()。以电脑网站支付为例业务参数是一个 JSON包含订单号、金额、标题等AlipayTradePagePayRequest request new AlipayTradePagePayRequest(); request.setNotifyUrl(notifyUrl); request.setReturnUrl(returnUrl); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, orderNo); bizContent.put(total_amount, amount); bizContent.put(subject, subject); bizContent.put(product_code, FAST_INSTANT_TRADE_PAY); request.setBizContent(bizContent.toJSONString()); String form alipayClient.pageExecute(request).getBody();这里pageExecute返回的是一段 HTML 表单直接输出到页面就会自动跳转到支付宝。如果是 APP 支付用的是sdkExecute返回的是给客户端调用的参数字符串。几个关键参数说明out_trade_no你的系统里的订单号必须唯一。重复的订单号支付宝会拒绝这是防止重复下单的机制。total_amount金额单位是元保留两位小数。注意不要传成“分”这是新手常犯的错误。product_code产品码不同支付产品不一样电脑网站是FAST_INSTANT_TRADE_PAYAPP 支付是QUICK_MSECURITY_PAY。实操心得out_trade_no建议用“业务前缀 时间戳 随机数”的格式既保证唯一又方便排查。不要用纯自增 ID因为不同业务线的订单号可能冲突。3.2 异步通知的验签与幂等处理异步通知是支付接入里最需要小心处理的部分。支付宝会 POST 一堆参数到你的notify_url你需要做这几件事验签用支付宝公钥验证请求参数的签名确认是支付宝发来的不是伪造的核对业务参数检查out_trade_no是不是你的订单total_amount是不是和订单金额一致app_id是不是你的处理业务更新订单状态、发货、通知等返回success告诉支付宝你处理成功了否则支付宝会按策略重推。验签用官方 SDK 的RSA2.check()或者AlipaySignature.rsaCheckV1()MapString, String params ...; // 从 request 里取所有参数 boolean signVerified AlipaySignature.rsaCheckV1( params, alipayPublicKey, UTF-8, RSA2); if (!signVerified) { // 验签失败直接返回 failure return failure; }验签通过后还要核对trade_status。只有TRADE_SUCCESS和TRADE_FINISHED才代表支付成功其他状态如WAIT_BUYER_PAY不能当作成功处理。幂等处理是这里的关键。支付宝可能因为网络原因重复推送同一条通知你的代码必须保证同一笔订单只处理一次。常见做法是用订单号做唯一索引更新时用update ... where status 待支付靠数据库的行锁保证只更新一次或者用 Redis 的setnx做分布式锁处理前先抢锁。我一般用数据库乐观更新简单可靠UPDATE orders SET status 已支付, pay_time NOW() WHERE order_no ? AND status 待支付;如果影响行数是 1说明这次是首次处理继续做后续业务如果是 0说明已经处理过了直接返回success即可。注意返回给支付宝的必须是纯字符串success不能带任何 HTML 标签或多余字符否则支付宝会认为你没处理成功一直重推。这个坑我踩过当时返回了一个 JSON结果支付宝推了十几次。3.3 退款接口的实现退款用的是AlipayTradeRefundRequest核心参数是out_trade_no或trade_no和refund_amountAlipayTradeRefundRequest request new AlipayTradeRefundRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, orderNo); bizContent.put(refund_amount, refundAmount); bizContent.put(out_request_no, refundNo); // 退款请求号支持部分退款 request.setBizContent(bizContent.toJSONString()); AlipayTradeRefundResponse response alipayClient.execute(request); if (response.isSuccess()) { // 退款成功 }退款有几个要点部分退款必须传out_request_no且每次退款的这个号要唯一否则支付宝会认为是同一笔退款退款是异步的接口返回成功只代表退款请求被受理实际到账时间取决于银行退款也要做幂等避免重复退款。我见过有项目退款没做幂等用户点两次退款按钮就退了两笔最后只能自己贴钱。所以退款前一定要先查一下这笔订单的退款状态。4. 常见问题与排查技巧实录这一节是我这些年踩坑的总结基本都是文档里不会写、但实际一定会遇到的问题。4.1 验签失败的几种典型原因验签失败是最高频的问题原因通常有这几类现象可能原因排查方法一直验签失败支付宝公钥配错确认用的是支付宝公钥不是应用公钥沙箱正常正式失败环境密钥混用检查网关地址和密钥是否匹配环境偶发验签失败参数编码问题确认字符集统一为 UTF-8回调验签失败参数被框架处理过用原始 request 取参数不要用被 Spring 包装过的最常见的是支付宝公钥配错。很多人把自己生成的应用公钥当成支付宝公钥填进去结果怎么都验不过。记住应用公钥是上传给支付宝的支付宝公钥是支付宝给你的两者不能混。还有一个隐蔽的坑如果你的项目用了网关或反向代理回调请求的参数可能被重新编码导致验签失败。这时候需要从原始输入流里读参数而不是从request.getParameterMap()取。4.2 异步通知收不到的排查如果订单一直显示待支付但用户说已经付了那大概率是异步通知没收到或没处理成功。排查顺序确认notify_url是公网可访问的。本地开发环境支付宝是访问不到的必须用内网穿透工具或者部署到测试服务器。这里说的内网穿透是开发调试用的合法工具用于把本地服务暴露到公网方便测试。确认notify_url没有重定向。支付宝不会跟随 302 跳转如果这个地址返回 302通知就丢了。确认返回了success。如果业务处理抛异常没返回success支付宝会重推但如果一直失败最终会放弃。查支付宝的商户平台。开放平台有“交易查询”和“通知记录”可以看到通知的发送和响应情况这是最直接的排查手段。我一般会在notify_url的入口打一条日志记录收到的原始参数和返回结果出问题时一看日志就清楚了。4.3 金额与订单号相关的坑金额方面最常见的错误是单位搞混。支付宝的total_amount单位是元但有些内部系统用分转换时容易出错。建议在代码里统一用BigDecimal并且明确注释单位。订单号方面out_trade_no必须唯一且长度有限制一般不超过 64 位。如果用了 UUID 或者雪花 ID注意长度。另外订单号里不要包含特殊字符否则可能被支付宝拒绝。还有一个坑是重复下单。如果用户快速点两次支付按钮可能生成两笔订单。解决办法是在下单前先查一下这个订单号是否已经存在或者用分布式锁控制。4.4 退款相关的常见问题退款失败的原因通常有订单未支付或已全额退款退款金额超过可退金额out_request_no重复账户余额不足这个比较少见但确实会发生。退款接口返回的sub_code和sub_msg是排查的关键比如ACQ.TRADE_NOT_EXIST表示交易不存在ACQ.REFUND_AMT_NOT_EQUAL_TOTAL表示退款金额不对。建议把这些错误码整理成一张表方便快速定位。5. 对账、安全与上线前的检查清单支付功能上线前光跑通流程是不够的还得考虑对账、安全和异常兜底。5.1 对账机制的设计对账的目的是发现“支付宝认为成功的订单”和“你系统里认为成功的订单”之间的差异。常见做法是每天定时拉取支付宝的对账单和你的订单表做比对。支付宝提供了对账单下载接口可以按日期下载 CSV 格式的账单。解析后逐笔核对订单号、金额、状态。差异通常有几类支付宝成功但你系统未更新异步通知丢失你系统成功但支付宝没有极少见可能是数据错误金额不一致严重问题需要人工介入。对账任务建议放在凌晨低峰期跑并且要有告警机制发现差异立即通知相关人员。5.2 安全方面的注意事项支付相关的安全核心是密钥保护和参数校验。密钥方面前面说过不要硬编码要用配置中心或环境变量。另外私钥文件权限要控制好不要放在 Web 可访问的目录下。参数校验方面回调处理时一定要核对app_id、out_trade_no、total_amount不能只验签就完事。因为验签只能证明请求来自支付宝不能证明这笔订单就是你的、金额就是对的。还有一点不要把敏感信息打到日志里比如完整的密钥、用户的支付账号等。日志脱敏是基本要求。5.3 上线前的检查清单最后给一份我常用的上线检查清单照着过一遍基本不会漏[ ] 正式环境的 AppId、密钥、网关地址配置正确[ ]notify_url和return_url是正式域名且公网可访问[ ] 异步通知的验签、金额核对、幂等处理都已实现[ ] 退款接口做了幂等和金额校验[ ] 对账任务已配置并测试通过[ ] 异常情况有告警如通知处理失败、对账差异[ ] 日志脱敏密钥不落盘到代码仓库[ ] 沙箱全流程测试通过包括支付、退款、查询。这套流程我在几个项目里都用过基本能覆盖大部分场景。支付接入这件事说难不难但细节特别多任何一个环节疏忽都可能导致资金问题。所以宁可前期多花点时间把每个环节都测透也不要上线后天天救火。我个人在实际操作中的体会是支付接入最值钱的不是代码写得多漂亮而是对异常情况的处理是否周全。正常流程谁都能跑通真正拉开差距的是那些“用户付了钱但订单没更新”“重复通知导致重复发货”的边界情况。把这些想清楚、测到位才算真正把支付接明白了。 
长河君 · 2026/10/15 10:10:02 · 阅读 1.2k Java对接支付宝支付实战：从下单回调到对账的完整避坑指南
1. 支付接入的整体设计与核心思路拆解做过电商或者任何有交易环节的系统支付接入基本是绕不开的一关。我前后在几个项目里对接过支付宝的多种支付产品从最早的即时到账到后来的当面付、手机网站支付、APP支付踩过的坑不算少。这篇就把“Java 对接支付宝支付”这件事从头到尾拆一遍重点讲清楚设计思路、参数怎么算、代码怎么写、出问题怎么查。先说清楚这个内容适合谁看如果你是一个 Java 后端开发者手上有一个需要收钱的项目不管是 Web 网站、手机 H5、还是原生 APP需要把支付宝的支付能力接进来那这篇基本能覆盖你 80% 的场景。如果你已经接过一次但总是被回调、验签、退款这些问题卡住那这篇里的排查部分应该能帮你省不少时间。支付宝支付接入的本质其实就三件事下单、回调、对账。下单是你告诉支付宝“有这么一笔订单用户要付这么多钱”回调是支付宝告诉你“这笔钱用户付了结果是这样”对账是你自己核对“支付宝说的和我记的账对不对得上”。听起来简单但每一环都有细节尤其是签名验签和异步通知的幂等处理是新手最容易翻车的地方。1.1 为什么选支付宝开放平台而不是老接口早些年支付宝有“即时到账”这类老网关接口现在基本都迁移到支付宝开放平台OpenAPI体系下了。这个迁移不是换个地址那么简单核心变化在于老接口用的是 MD5 或 RSA 的简单签名密钥管理比较粗放开放平台统一用RSA2SHA256WithRSA签名安全性更高开放平台有统一的网关地址、统一的应用模型AppId 应用私钥 支付宝公钥支持的能力更全当面付、APP 支付、手机网站支付、电脑网站支付、小程序支付都在同一套体系里。所以现在做新项目直接上开放平台就对了别再去翻那些老文档。我见过有团队还在用老接口结果遇到退款、对账各种不兼容最后还是要重做一遍纯属浪费时间。1.2 核心概念先理清楚在动手写代码之前有几个概念必须先搞明白否则后面看文档会一头雾水。AppId你在开放平台创建应用后拿到的唯一标识相当于你的“商户身份证号”。应用私钥 / 应用公钥你自己生成的一对密钥私钥留在你服务器上用来签名公钥上传到开放平台让支付宝验证你的签名。支付宝公钥支付宝那边的一对密钥里的公钥你下载下来用来验证支付宝返回数据的签名。注意这个和你自己的应用公钥是两回事很多人第一次接会把这两个搞混。网关地址正式环境是https://openapi.alipay.com/gateway.do沙箱环境是https://openapi.alipaydev.com/gateway.do。沙箱用来测试正式上线要换成正式的。异步通知notify_url支付宝在用户支付成功后会主动 POST 一个请求到你指定的这个地址告诉你支付结果。这是你更新订单状态的主要依据。同步跳转return_url用户支付完成后浏览器跳转回的页面主要用于展示“支付成功”给用户看不能作为订单状态的依据因为用户可以伪造这个跳转。这里划重点订单状态的最终确认必须以异步通知为准同步跳转只能用来做页面展示。我见过有项目只处理同步跳转结果用户关掉页面订单就一直是待支付这就是典型的踩坑。1.3 整体流程设计一笔支付从用户点击到订单完成完整链路是这样的用户在你的系统里点击“去支付”你的后端调用支付宝的统一下单接口生成一个支付链接或支付参数用户被引导到支付宝完成付款支付宝异步 POST 通知你的notify_url你验签、核对金额、更新订单状态返回success支付宝同步跳转用户到return_url你展示支付结果页面后续通过定时对账任务拉取支付宝账单和你自己的订单做核对。这个链路里第 3 步是核心也是最容易出问题的地方。验签失败、金额对不上、重复通知、返回的不是success导致支付宝反复重推这些都是常见故障。后面我会专门用一节来讲这些问题的排查。2. 密钥、依赖与基础配置的实操要点这一节讲动手前的准备工作。别小看这些配置我见过太多项目卡在密钥格式不对、依赖版本冲突这种“低级”问题上一卡就是半天。2.1 密钥生成与格式处理支付宝官方提供了一个密钥生成工具可以生成 RSA2 密钥对。生成出来的是两个文件应用私钥和应用公钥。这里有几个细节要注意。第一私钥格式。工具生成的私钥通常是 PKCS8 格式的内容是一长串 Base64。你在代码里用的时候需要把它还原成PrivateKey对象。很多人直接把带-----BEGIN PRIVATE KEY-----头尾的字符串丢进去结果报错因为 SDK 需要的是纯 Base64 内容或者你需要自己处理头尾。第二支付宝公钥的获取。上传应用公钥后开放平台会给你一个支付宝公钥。注意如果你用的是“公钥模式”拿到的是支付宝公钥如果用的是“证书模式”那又是另一套东西。新手建议先用公钥模式简单直接。第三密钥不要硬编码在代码里。这是安全大忌。正确做法是放在配置中心或者环境变量里代码里只读配置。我见过有项目把私钥直接写在application.yml里提交到代码仓库这等于把保险箱钥匙挂在门上。下面是一个读取私钥的典型写法public static PrivateKey loadPrivateKey(String privateKeyStr) throws Exception { // 去掉头尾和换行 String content privateKeyStr .replace(-----BEGIN PRIVATE KEY-----, ) .replace(-----END PRIVATE KEY-----, ) .replaceAll(\\s, ); byte[] keyBytes Base64.getDecoder().decode(content); PKCS8EncodedKeySpec spec new PKCS8EncodedKeySpec(keyBytes); KeyFactory kf KeyFactory.getInstance(RSA); return kf.generatePrivate(spec); }这段代码的关键在于把 Base64 内容里的空白字符全部去掉否则解码会失败。这个坑我踩过当时排查了半天才发现是配置文件里换行符的问题。2.2 依赖选型官方 SDK 还是自己封装支付宝官方提供了 Java SDKMaven 坐标是com.alipay.sdk:alipay-sdk-java。我的建议是直接用官方 SDK不要自己从零封装签名和 HTTP 请求。原因很简单签名算法、参数排序、编码处理这些细节官方 SDK 都处理好了自己写容易出错官方 SDK 会跟进接口变化维护成本低出问题时社区和文档都基于官方 SDK排查方便。不过官方 SDK 也有个毛病就是版本更新比较频繁而且不同版本之间偶尔有 API 变化。建议锁定一个稳定版本不要盲目追新。我一般用比较成熟的版本比如4.x系列里经过验证的版本。如果你用的是 Spring Boot可以配合一个配置类来初始化AlipayClientConfiguration public class AlipayConfig { Value(${alipay.app-id}) private String appId; Value(${alipay.private-key}) private String privateKey; Value(${alipay.alipay-public-key}) private String alipayPublicKey; Value(${alipay.gateway-url}) private String gatewayUrl; Bean public AlipayClient alipayClient() { return new DefaultAlipayClient( gatewayUrl, appId, privateKey, json, UTF-8, alipayPublicKey, RSA2); } }注意DefaultAlipayClient的构造参数顺序网关、AppId、私钥、格式、字符集、支付宝公钥、签名类型。这个顺序记错了会直接报错而且报错信息不一定直观。2.3 沙箱环境的使用正式接入前强烈建议先在沙箱环境跑通全流程。沙箱环境有独立的 AppId、密钥和买家账号可以模拟支付、退款、查询等操作不会产生真实资金流动。沙箱的坑在于沙箱的网关地址和正式不一样密钥也是独立的不能混用。我见过有人把沙箱的密钥配到正式环境结果一直验签失败查了半天才发现是环境搞混了。所以配置里最好把沙箱和正式分开管理用 profile 或者配置中心区分。3. 下单、回调与退款的完整实现这一节是核心把下单、异步通知、退款这三个最常用的能力讲透。3.1 统一下单接口的调用支付宝的支付产品很多但下单的调用方式大同小异都是构造一个AlipayTradeXxxRequest设置业务参数然后调用alipayClient.execute()或pageExecute()。以电脑网站支付为例业务参数是一个 JSON包含订单号、金额、标题等AlipayTradePagePayRequest request new AlipayTradePagePayRequest(); request.setNotifyUrl(notifyUrl); request.setReturnUrl(returnUrl); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, orderNo); bizContent.put(total_amount, amount); bizContent.put(subject, subject); bizContent.put(product_code, FAST_INSTANT_TRADE_PAY); request.setBizContent(bizContent.toJSONString()); String form alipayClient.pageExecute(request).getBody();这里pageExecute返回的是一段 HTML 表单直接输出到页面就会自动跳转到支付宝。如果是 APP 支付用的是sdkExecute返回的是给客户端调用的参数字符串。几个关键参数说明out_trade_no你的系统里的订单号必须唯一。重复的订单号支付宝会拒绝这是防止重复下单的机制。total_amount金额单位是元保留两位小数。注意不要传成“分”这是新手常犯的错误。product_code产品码不同支付产品不一样电脑网站是FAST_INSTANT_TRADE_PAYAPP 支付是QUICK_MSECURITY_PAY。实操心得out_trade_no建议用“业务前缀 时间戳 随机数”的格式既保证唯一又方便排查。不要用纯自增 ID因为不同业务线的订单号可能冲突。3.2 异步通知的验签与幂等处理异步通知是支付接入里最需要小心处理的部分。支付宝会 POST 一堆参数到你的notify_url你需要做这几件事验签用支付宝公钥验证请求参数的签名确认是支付宝发来的不是伪造的核对业务参数检查out_trade_no是不是你的订单total_amount是不是和订单金额一致app_id是不是你的处理业务更新订单状态、发货、通知等返回success告诉支付宝你处理成功了否则支付宝会按策略重推。验签用官方 SDK 的RSA2.check()或者AlipaySignature.rsaCheckV1()MapString, String params ...; // 从 request 里取所有参数 boolean signVerified AlipaySignature.rsaCheckV1( params, alipayPublicKey, UTF-8, RSA2); if (!signVerified) { // 验签失败直接返回 failure return failure; }验签通过后还要核对trade_status。只有TRADE_SUCCESS和TRADE_FINISHED才代表支付成功其他状态如WAIT_BUYER_PAY不能当作成功处理。幂等处理是这里的关键。支付宝可能因为网络原因重复推送同一条通知你的代码必须保证同一笔订单只处理一次。常见做法是用订单号做唯一索引更新时用update ... where status 待支付靠数据库的行锁保证只更新一次或者用 Redis 的setnx做分布式锁处理前先抢锁。我一般用数据库乐观更新简单可靠UPDATE orders SET status 已支付, pay_time NOW() WHERE order_no ? AND status 待支付;如果影响行数是 1说明这次是首次处理继续做后续业务如果是 0说明已经处理过了直接返回success即可。注意返回给支付宝的必须是纯字符串success不能带任何 HTML 标签或多余字符否则支付宝会认为你没处理成功一直重推。这个坑我踩过当时返回了一个 JSON结果支付宝推了十几次。3.3 退款接口的实现退款用的是AlipayTradeRefundRequest核心参数是out_trade_no或trade_no和refund_amountAlipayTradeRefundRequest request new AlipayTradeRefundRequest(); JSONObject bizContent new JSONObject(); bizContent.put(out_trade_no, orderNo); bizContent.put(refund_amount, refundAmount); bizContent.put(out_request_no, refundNo); // 退款请求号支持部分退款 request.setBizContent(bizContent.toJSONString()); AlipayTradeRefundResponse response alipayClient.execute(request); if (response.isSuccess()) { // 退款成功 }退款有几个要点部分退款必须传out_request_no且每次退款的这个号要唯一否则支付宝会认为是同一笔退款退款是异步的接口返回成功只代表退款请求被受理实际到账时间取决于银行退款也要做幂等避免重复退款。我见过有项目退款没做幂等用户点两次退款按钮就退了两笔最后只能自己贴钱。所以退款前一定要先查一下这笔订单的退款状态。4. 常见问题与排查技巧实录这一节是我这些年踩坑的总结基本都是文档里不会写、但实际一定会遇到的问题。4.1 验签失败的几种典型原因验签失败是最高频的问题原因通常有这几类现象可能原因排查方法一直验签失败支付宝公钥配错确认用的是支付宝公钥不是应用公钥沙箱正常正式失败环境密钥混用检查网关地址和密钥是否匹配环境偶发验签失败参数编码问题确认字符集统一为 UTF-8回调验签失败参数被框架处理过用原始 request 取参数不要用被 Spring 包装过的最常见的是支付宝公钥配错。很多人把自己生成的应用公钥当成支付宝公钥填进去结果怎么都验不过。记住应用公钥是上传给支付宝的支付宝公钥是支付宝给你的两者不能混。还有一个隐蔽的坑如果你的项目用了网关或反向代理回调请求的参数可能被重新编码导致验签失败。这时候需要从原始输入流里读参数而不是从request.getParameterMap()取。4.2 异步通知收不到的排查如果订单一直显示待支付但用户说已经付了那大概率是异步通知没收到或没处理成功。排查顺序确认notify_url是公网可访问的。本地开发环境支付宝是访问不到的必须用内网穿透工具或者部署到测试服务器。这里说的内网穿透是开发调试用的合法工具用于把本地服务暴露到公网方便测试。确认notify_url没有重定向。支付宝不会跟随 302 跳转如果这个地址返回 302通知就丢了。确认返回了success。如果业务处理抛异常没返回success支付宝会重推但如果一直失败最终会放弃。查支付宝的商户平台。开放平台有“交易查询”和“通知记录”可以看到通知的发送和响应情况这是最直接的排查手段。我一般会在notify_url的入口打一条日志记录收到的原始参数和返回结果出问题时一看日志就清楚了。4.3 金额与订单号相关的坑金额方面最常见的错误是单位搞混。支付宝的total_amount单位是元但有些内部系统用分转换时容易出错。建议在代码里统一用BigDecimal并且明确注释单位。订单号方面out_trade_no必须唯一且长度有限制一般不超过 64 位。如果用了 UUID 或者雪花 ID注意长度。另外订单号里不要包含特殊字符否则可能被支付宝拒绝。还有一个坑是重复下单。如果用户快速点两次支付按钮可能生成两笔订单。解决办法是在下单前先查一下这个订单号是否已经存在或者用分布式锁控制。4.4 退款相关的常见问题退款失败的原因通常有订单未支付或已全额退款退款金额超过可退金额out_request_no重复账户余额不足这个比较少见但确实会发生。退款接口返回的sub_code和sub_msg是排查的关键比如ACQ.TRADE_NOT_EXIST表示交易不存在ACQ.REFUND_AMT_NOT_EQUAL_TOTAL表示退款金额不对。建议把这些错误码整理成一张表方便快速定位。5. 对账、安全与上线前的检查清单支付功能上线前光跑通流程是不够的还得考虑对账、安全和异常兜底。5.1 对账机制的设计对账的目的是发现“支付宝认为成功的订单”和“你系统里认为成功的订单”之间的差异。常见做法是每天定时拉取支付宝的对账单和你的订单表做比对。支付宝提供了对账单下载接口可以按日期下载 CSV 格式的账单。解析后逐笔核对订单号、金额、状态。差异通常有几类支付宝成功但你系统未更新异步通知丢失你系统成功但支付宝没有极少见可能是数据错误金额不一致严重问题需要人工介入。对账任务建议放在凌晨低峰期跑并且要有告警机制发现差异立即通知相关人员。5.2 安全方面的注意事项支付相关的安全核心是密钥保护和参数校验。密钥方面前面说过不要硬编码要用配置中心或环境变量。另外私钥文件权限要控制好不要放在 Web 可访问的目录下。参数校验方面回调处理时一定要核对app_id、out_trade_no、total_amount不能只验签就完事。因为验签只能证明请求来自支付宝不能证明这笔订单就是你的、金额就是对的。还有一点不要把敏感信息打到日志里比如完整的密钥、用户的支付账号等。日志脱敏是基本要求。5.3 上线前的检查清单最后给一份我常用的上线检查清单照着过一遍基本不会漏[ ] 正式环境的 AppId、密钥、网关地址配置正确[ ]notify_url和return_url是正式域名且公网可访问[ ] 异步通知的验签、金额核对、幂等处理都已实现[ ] 退款接口做了幂等和金额校验[ ] 对账任务已配置并测试通过[ ] 异常情况有告警如通知处理失败、对账差异[ ] 日志脱敏密钥不落盘到代码仓库[ ] 沙箱全流程测试通过包括支付、退款、查询。这套流程我在几个项目里都用过基本能覆盖大部分场景。支付接入这件事说难不难但细节特别多任何一个环节疏忽都可能导致资金问题。所以宁可前期多花点时间把每个环节都测透也不要上线后天天救火。我个人在实际操作中的体会是支付接入最值钱的不是代码写得多漂亮而是对异常情况的处理是否周全。正常流程谁都能跑通真正拉开差距的是那些“用户付了钱但订单没更新”“重复通知导致重复发货”的边界情况。把这些想清楚、测到位才算真正把支付接明白了。