2. 支付宝支付SDK核心接口梳理

支付宝支付SDK围绕支付、授权、订单查询与回调处理四大核心领域提供标准化接口。本章深入分析各接口的设计原理、调用流程、常见参数与返回结构，并通过内联SVG展示接口之间的协作关系，为后续Compose桥接打下牢固基础。

2.1 支付接口：alipayClient.execute

支付接口是SDK最核心的入口，用于发起App支付、手机网站支付等请求。其本质是向支付宝服务器提交交易订单，并返回用于客户端调用的字符串（如orderInfo）。

原理

• 签名机制：商户服务端使用RSA私钥对订单参数串进行签名，SDK将携带签名的orderInfo传给支付宝客户端。
• 支付流程：支付宝客户端解析orderInfo后唤起收银台，用户完成支付，支付宝后台同步返回处理结果。

核心API示例（Kotlin）

// 构造支付请求参数
val payRequest = AlipayTradeAppPayRequest().apply {
    notifyUrl = "https://yourdomain.com/pay/notify"
    bizContent = """
        {
            "subject": "测试商品",
            "out_trade_no": "${System.currentTimeMillis()}",
            "total_amount": "0.01",
            "product_code": "QUICK_MSECURITY_PAY"
        }
    """.trimIndent()
}

// 执行请求（需在IO线程）
val response = AlipayClient.execute(payRequest)

// 获取orderInfo字符串传递给支付宝App
val orderInfo = response.body
// 通过callback处理客户端返回结果

2.2 授权接口：OAuth2.0 与 alipay.user.info

授权接口用于获取用户支付宝账号的授权信息（头像、昵称、用户ID等），通常用于登录场景。原理基于OAuth2.0授权码模式：

• App唤起支付宝授权页面，用户同意后获得authCode。
• 服务端使用authCode换取access_和用户信息。

API调用示例（服务端Java）

// 第一步：构造授权链接（客户端唤起使用）
String url = "https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?" +
    "app_id=" + appId +
    "&scope=auth_user" +
    "&redirect_uri=" + URLEncoder.encode("alipay://callback", "UTF-8");

// 第二步：服务端根据authCode获取
AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest();
request.setGrantType("authorization_code");
request.setCode(authCode);
AlipaySystemOauthTokenResponse response = alipayClient.execute(request);
String accessToken = response.getAccessToken();

// 第三步：查询用户信息
AlipayUserInfoShareRequest userReq = new AlipayUserInfoShareRequest();
AlipayUserInfoShareResponse userResp = alipayClient.execute(userReq, accessToken);
log.info("用户昵称：{}", userResp.getNickName());

2.3 订单查询功能：alipay.trade.query

订单查询是支付成功率的保障，适用于以下场景：

• 支付结果回调丢失或延迟，通过主动查询确认交易状态。
• 对账：定期扫描未完成订单，调用查询接口进行补偿。

请求参数与返回结构

示例代码（Kotlin协程）

data class TradeStatusResponse(
    val outTradeNo: String,
    val tradeNo: String,
    val tradeStatus: String,
    val totalAmount: String
)

suspend fun queryTrade(orderId: String): TradeStatusResponse {
    val request = AlipayTradeQueryRequest().apply {
        bizContent = """{"out_trade_no": "$orderId"}"""
    }
    val response = alipayClient.execute(request) // IO线程
    val body = JSONObject(response.body)
    return TradeStatusResponse(
        outTradeNo = body.getString("out_trade_no"),
        tradeNo = body.getString("trade_no"),
        tradeStatus = body.getString("trade_status"),
        totalAmount = body.getString("total_amount")
    )
}

2.4 回调处理类：NotifyReceiver & AuthCallback

回调处理是支付宝SDK异步通知的终点，分为两类：

• 服务端异步通知：支付宝在支付完成后向商户notify_url发送POST请求，携带交易参数与签名。
• 客户端同步回调：支付成功后支付宝App通过intent或URL Scheme返回结果码（9000成功、8000处理中等）。

服务端验签核心逻辑

String sign = request.getParameter("sign");
String content = AlipaySignature.getSignCheckContentV2(request.getParameterMap());
boolean isVaild = AlipaySignature.rsaCheckV2(content, sign, alipayPublicKey, "UTF-8");

if (isVaild) {
    String tradeStatus = request.getParameter("trade_status");
    if ("TRADE_SUCCESS".equals(tradeStatus)) {
        // 更新订单状态，返回success给支付宝
        response.getWriter().write("success");
    }
} else {
    // 验签失败，记录日志并丢弃
    log.warn("异步通知验签失败，参数: {}", request.getParameterMap());
}

2.5 接口调用流程总览

以下流程步骤归纳了支付、授权、查询与回调的完整协作关系：

1. 支付发起：服务端组装订单参数并签名，返回orderInfo给App。
2. 唤起支付：App通过SDK的AlipaySDK.payV2(orderInfo, true)唤起支付宝客户端。
3. 同步回调：支付完成，支付宝App通过Intent回调返回结果码（9000/8000/6001等）。
4. 异步通知：支付宝服务器向notify_url发送POST请求，包含完整交易数据和签名。
5. 服务端处理：验签通过后更新订单状态，返回"success"给支付宝。
6. 订单补偿查询：若异步通知超时或丢失，App可主动调用alipay.trade.query确认状态。
7. 授权流程：用户授权后获得authCode，服务端换取access_后调用用户信息接口。