支付宝授权与支付需要哪些 jar 包？

2026-10-24支付小周

明确结论

在 Java 服务端接入支付宝授权和支付，通常引入支付宝 Java SDK 即可：

<dependency>
    <groupId>com.alipay.sdk</groupId>
    <artifactId>alipay-sdk-java</artifactId>
    <version>请填写支付宝开放平台当前推荐的稳定版本</version>
</dependency>

建议使用 Maven 或 Gradle 管理依赖，不要手动收集零散的 jar 包。alipay-sdk-java 包含授权、支付、退款、订单查询和异步通知验签等接口所需的核心类，相关依赖也会由构建工具自动传递引入。

具体版本应以支付宝开放平台文档和 Maven 仓库实际发布的版本为准，不要照搬旧示例中的固定版本。

为什么一个 SDK 通常就够了

支付宝网页授权和支付属于不同业务，但服务端的调用方式大致相同：

授权用于获取 auth_code，再换取 access_token 或用户信息。
支付涉及创建交易、查询订单、退款和关闭订单。
处理回调时需要验证支付宝签名。
Java SDK 可以完成请求签名、响应解析和验签。

常用的核心类有：

com.alipay.api.AlipayClient
com.alipay.api.DefaultAlipayClient
com.alipay.api.AlipayApiException
com.alipay.api.internal.util.AlipaySignature

每个接口都有对应的 Request 和 Response 类。支付场景可能会用到：

AlipayTradePagePayRequest
AlipayTradeAppPayRequest
AlipayTradePrecreateRequest
AlipayTradeQueryRequest
AlipayTradeRefundRequest

授权场景通常会使用系统 OAuth Token 相关请求类。准确的类名应以所选 SDK 版本和支付宝开放平台对应产品的文档为准。

Maven 引入方式

在 pom.xml 中添加依赖：

<dependencies>
    <dependency>
        <groupId>com.alipay.sdk</groupId>
        <artifactId>alipay-sdk-java</artifactId>
        <version>${alipay.sdk.version}</version>
    </dependency>
</dependencies>

可以把版本统一放在属性中管理：

<properties>
    <alipay.sdk.version>实际使用的稳定版本</alipay.sdk.version>
</properties>

添加后执行：

mvn dependency:tree

通过依赖树可以确认 SDK 及其传递依赖是否正确加载，同时排查重复依赖和版本冲突。

Gradle 引入方式

Groovy DSL：

dependencies {
    implementation "com.alipay.sdk:alipay-sdk-java:实际使用的稳定版本"
}

Kotlin DSL：

dependencies {
    implementation("com.alipay.sdk:alipay-sdk-java:实际使用的稳定版本")
}

初始化支付宝客户端

引入 SDK 后，可以在服务端创建 AlipayClient：

import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;

AlipayClient alipayClient = new DefaultAlipayClient(
    "https://openapi.alipay.com/gateway.do",
    appId,
    merchantPrivateKey,
    "json",
    "UTF-8",
    alipayPublicKey,
    "RSA2"
);

沙箱环境和正式环境使用不同的网关、应用 ID、密钥及其他配置。上线前需要确认所有参数都属于对应环境。

支付请求示例

下面以电脑网站支付为例：

import com.alipay.api.AlipayClient;
import com.alipay.api.response.AlipayTradePagePayResponse;
import com.alipay.api.request.AlipayTradePagePayRequest;

AlipayTradePagePayRequest request = new AlipayTradePagePayRequest();
request.setReturnUrl("https://example.com/alipay/return");
request.setNotifyUrl("https://example.com/alipay/notify");

request.setBizContent("""
{
  "out_trade_no": "ORDER_202609090001",
  "total_amount": "99.00",
  "subject": "测试订单",
  "product_code": "FAST_INSTANT_TRADE_PAY"
}
""");

AlipayTradePagePayResponse response = alipayClient.pageExecute(request);

if (response.isSuccess()) {
    String paymentForm = response.getBody();
    // 将表单内容返回给浏览器，由浏览器跳转到支付宝收银台
} else {
    // 记录 response.getCode()、response.getMsg() 等信息
}

不同支付产品使用的接口不同。App 支付、电脑网站支付、手机网站支付和当面付不能简单共用同一个 Request 类。

授权处理思路

网页授权通常包括以下步骤：

按照支付宝开放平台的要求拼接授权地址。
用户确认授权后，支付宝将浏览器重定向到回调地址。
服务端从回调参数中获取 auth_code。
使用 SDK 调用 OAuth Token 接口，用 auth_code 换取授权令牌。
根据业务需要保存令牌，并处理令牌刷新和失效逻辑。

示意代码如下：

import com.alipay.api.request.AlipaySystemOauthTokenRequest;
import com.alipay.api.response.AlipaySystemOauthTokenResponse;

AlipaySystemOauthTokenRequest request =
    new AlipaySystemOauthTokenRequest();

request.setGrantType("authorization_code");
request.setCode(authCode);

AlipaySystemOauthTokenResponse response = alipayClient.execute(request);

if (response.isSuccess()) {
    String accessToken = response.getAccessToken();
    String userId = response.getUserId();
} else {
    // 根据错误码记录并处理授权失败
}

部分字段是否返回、用户标识的具体类型以及后续可调用的用户信息接口，取决于应用类型、授权范围和开放平台当前的规则。

异步通知验签

确认支付成功时，不能只看浏览器的同步跳转结果，应以服务端异步通知为主，并结合主动查询。回调验签可以使用 SDK 提供的工具类：

import com.alipay.api.internal.util.AlipaySignature;

boolean verified = AlipaySignature.rsaCheckV1(
    parameterMap,
    alipayPublicKey,
    "UTF-8",
    "RSA2"
);

验签成功后，还需要检查：

app_id 是否属于当前应用。
out_trade_no 是否存在，且属于当前商户。
total_amount 是否与本地订单金额一致。
seller_id 等商户信息是否匹配。
订单是否已经处理，避免重复通知造成重复发货。
交易状态是否符合业务处理条件。

手动引入 jar 时怎么处理

如果项目无法使用 Maven 或 Gradle，可以下载支付宝 Java SDK 的 jar，并将其放入项目的依赖目录，例如传统 Web 项目的 WEB-INF/lib。

不过，只复制 alipay-sdk-java-*.jar 不一定能正常运行。SDK 可能依赖 JSON、日志或其他基础库，而且具体依赖会随 SDK 版本变化。应查看对应版本的 POM 文件或发布说明，把运行时依赖一并加入，不要直接照搬旧项目的 jar 清单。

手动管理依赖时，常见问题有：

ClassNotFoundException
NoClassDefFoundError
JSON 组件版本冲突
日志门面或日志实现冲突
项目中同时存在多个版本的支付宝 SDK

只要项目支持构建工具，就应优先使用 Maven 或 Gradle。

Android 客户端需要注意

如果接入的是 Android App 支付，客户端通常还需要使用支付宝提供的移动支付 SDK。它可能以 AAR 或其他官方形式发布，不能用服务端的 alipay-sdk-java 代替。

客户端只负责唤起支付并接收初步结果。订单创建、参数签名和最终支付结果确认都应在服务端完成。商户应用私钥绝不能写入 Android 或 iOS 客户端，否则很容易被反编译获取。

常见误区

把授权 SDK 和支付 SDK 分开找

对于 Java 服务端，授权和支付通常都由同一个 alipay-sdk-java 提供，不需要分别寻找所谓的”授权 jar”和”支付 jar”。

同时引入新旧 SDK

旧项目中可能已经存在名称不同的历史 SDK。如果再加入新版 alipay-sdk-java，很容易出现同名类、接口差异或依赖冲突。升级前应检查现有依赖，并移除已经不再使用的旧包。

混淆支付宝公钥和应用公钥

应用公钥需要上传到支付宝开放平台，代码验签通常使用支付宝公钥。两者用途不同，配置错误会导致签名验证失败。

只相信客户端返回结果

客户端返回”支付成功”，不代表服务端已经确认收款。服务端应验证异步通知，必要时再调用交易查询接口核对订单状态。

总体而言，Java 服务端优先引入 com.alipay.sdk:alipay-sdk-java 即可。Android 或 iOS 客户端还需要接入相应的移动端支付 SDK。最终使用的依赖版本和接口能力，应与申请的支付宝产品、应用类型及开放平台最新接入文档一致。