WeChatDeveloper/docs/alipay.md

支付宝

支付宝客户端统一构造网关公共参数，使用应用私钥签名请求，并使用支付宝公钥验证同步响应和异步通知。

开放平台配置

<?php

declare(strict_types=1);

use We\Client;
use We\Config\AlipayPlatformConfig;

$config = new AlipayPlatformConfig(
    appid: '2026000000000000',
    privateKey: $applicationPrivateKey,
    alipayPublicKey: $alipayPublicKey,
    signType: 'RSA2',
);

$alipay = (new Client())->alipayPlatform($config);

privateKey 与 alipayPublicKey 都是必填安全配置。前者代表应用，后者代表支付宝平台。默认网关是 https://openapi.alipay.com/gateway.do。

完整 PEM 和无头尾的 RSA key body 都可使用；私钥支持 PKCS#1 与 PKCS#8。EC 等非 RSA 密钥会在配置阶段被拒绝。

网关调用

API method 与支付宝官方文档一致：

<?php

declare(strict_types=1);

$result = $alipay->post('alipay.user.info.share', [
    'auth_token' => 'user_auth_token',
]);

$authUrl = $alipay->auth(
    'https://example.com/alipay/callback',
    'auth_user',
    'state-value',
);

同步响应只有在下列条件全部满足时才返回数组：

1. JSON 可以解析。
2. 存在与 API method 对应的响应节点，或明确的 error_response。
3. 顶层存在签名，且原始响应节点通过支付宝公钥验签。
4. 响应节点存在标量 code。
5. code 等于 10000。

空 JSON、缺节点或缺 code 不会被当作成功，并抛出 AlipayApiException。缺签名或验签失败抛出 AlipaySignatureException。网络传输错误抛出 TransportException；平台业务错误的异常保留响应节点上下文。

支付客户端

<?php

declare(strict_types=1);

use We\Client;
use We\Config\AlipayPaymentConfig;

$payment = (new Client())->alipayPayment(new AlipayPaymentConfig(
    appid: '2026000000000000',
    privateKey: $applicationPrivateKey,
    alipayPublicKey: $alipayPublicKey,
));

$pageUrl = $payment->page([
    'out_trade_no' => 'A202608100001',
    'total_amount' => '0.01',
    'subject' => '测试订单',
    'product_code' => 'FAST_INSTANT_TRADE_PAY',
]);

$refund = $payment->refund([
    'out_trade_no' => 'A202608100001',
    'refund_amount' => '0.01',
]);

page() 返回已签名的电脑网站支付 URL；refund() 调用 alipay.trade.refund。其他支付 API 继续使用官方 method 调用 request()、get() 或 post()。

异步通知

业务处理前验证支付宝通知完整参数：

<?php

declare(strict_types=1);

$verified = $alipay->verifyNotify($_POST);
if (!$verified) {
    throw new RuntimeException('Invalid Alipay notification signature.');
}

验签会排除 sign 和 sign_type，按支付宝规则排序并拼接其他非空字段。返回 true 只证明参数签名有效；订单金额、商户身份、通知状态和业务幂等仍由业务系统校验。