AIGC/demo/ALIPAY_SETUP_GUIDE.md

支付宝支付集成准备指南

一、必需准备项

1. 支付宝商户账号

• 个人开发者：注册支付宝开放平台账号（https://open.alipay.com）
• 企业用户：需要营业执照等企业资质，申请企业支付宝账号

2. 创建应用并获取配置信息

登录支付宝开放平台后，需要创建应用并获取以下配置：

开发环境（沙箱测试）

• APPID（应用ID）：alipay.app-id
• 应用私钥（Private Key）：alipay.private-key
• 支付宝公钥（Public Key）：alipay.public-key
• 网关地址：https://openapi.alipaydev.com/gateway.do（沙箱）
• 字符集：UTF-8
• 签名方式：RSA2

生产环境

• 网关地址：https://openapi.alipay.com/gateway.do
• 其他配置同开发环境

3. 密钥生成和配置

支付宝使用RSA2签名，需要生成密钥对：

方法1：使用支付宝密钥生成工具

• 下载支付宝官方密钥生成工具
• 生成密钥对（RSA2，2048位）
• 保存私钥（用于配置 alipay.private-key）
• 将公钥上传到支付宝开放平台，获取支付宝公钥（用于配置 alipay.public-key）

方法2：使用OpenSSL生成

# 生成私钥
openssl genrsa -out app_private_key.pem 2048

# 生成公钥
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem

# 查看私钥内容（去除头尾，保留中间部分配置到private-key）
cat app_private_key.pem

# 将app_public_key.pem内容上传到支付宝开放平台

重要：

• 私钥需要去除 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----
• 私钥和公钥配置在配置文件中时，需要去掉换行符或使用转义

4. 配置回调地址

需要配置两个回调地址：

异步通知地址（notify-url）

• 用于接收支付宝的支付结果异步通知
• 必须是公网可访问的HTTPS地址
• 示例：https://yourdomain.com/api/payments/alipay/notify
• 注意：开发环境可以使用ngrok等内网穿透工具

同步返回地址（return-url）

• 用户支付完成后跳转的页面
• 可以是HTTP或HTTPS地址
• 示例：https://yourdomain.com/api/payments/alipay/return

5. 数据库表准备

项目已经包含了Payment相关表，确保数据库已创建：

• payments 表
• orders 表

6. Maven依赖（已配置）

项目已包含支付宝SDK依赖：

<dependency>
    <groupId>com.github.javen205</groupId>
    <artifactId>IJPay-AliPay</artifactId>
    <version>2.9.12.1</version>
</dependency>

二、配置文件设置

开发环境配置（application-dev.properties）

# 支付宝配置 (开发环境 - 沙箱测试)
alipay.app-id=你的沙箱APPID
alipay.private-key=你的应用私钥（去除头尾和换行）
alipay.public-key=支付宝公钥（从开放平台获取）
alipay.gateway-url=https://openapi.alipaydev.com/gateway.do
alipay.charset=UTF-8
alipay.sign-type=RSA2
alipay.notify-url=https://your-ngrok-url.ngrok-free.dev/api/payments/alipay/notify
alipay.return-url=https://your-ngrok-url.ngrok-free.dev/api/payments/alipay/return

生产环境配置（application-prod.properties）

# 支付宝配置 (生产环境)
alipay.app-id=${ALIPAY_APP_ID}
alipay.private-key=${ALIPAY_PRIVATE_KEY}
alipay.public-key=${ALIPAY_PUBLIC_KEY}
alipay.gateway-url=https://openapi.alipay.com/gateway.do
alipay.charset=UTF-8
alipay.sign-type=RSA2
alipay.notify-url=${ALIPAY_NOTIFY_URL}
alipay.return-url=${ALIPAY_RETURN_URL}

三、测试步骤

1. 沙箱测试环境准备

1. 登录支付宝开放平台：https://open.alipay.com
2. 进入"沙箱环境"
3. 获取沙箱APPID
4. 下载"支付宝密钥生成工具"，生成密钥对
5. 上传公钥到支付宝，获取支付宝公钥
6. 配置沙箱测试账号（买家账号和卖家账号）

2. 内网穿透配置（开发测试）

如果本地开发，需要使用ngrok等工具暴露本地服务：

# 安装ngrok
# 启动本地服务（端口8080）
# 使用ngrok暴露
ngrok http 8080
# 获取https地址，配置到notify-url和return-url

3. 功能测试

• 创建支付订单
• 生成支付宝二维码
• 使用沙箱账号扫码支付
• 验证异步通知接收
• 验证支付状态更新

四、已实现的功能

后端接口

✅ POST /api/payments/alipay/create - 创建支付宝支付并生成二维码 ✅ POST /api/payments/alipay/notify - 接收支付宝异步通知 ✅ GET /api/payments/alipay/return - 处理支付宝同步返回

前端页面

✅ 支付模态框组件（PaymentModal.vue） ✅ 订阅页面支付集成（Subscription.vue）

核心服务

✅ AlipayService - 支付宝服务封装

• createPayment() - 创建支付订单
• handleNotify() - 处理异步通知
• handleReturn() - 处理同步返回

五、常见问题

1. 签名验证失败

• 检查私钥和公钥是否正确配置
• 确认私钥格式正确（去除头尾和换行）
• 确认使用RSA2签名方式

2. 回调地址无法访问

• 确保回调地址是公网可访问的HTTPS地址
• 开发环境可以使用ngrok等内网穿透工具
• 检查防火墙和服务器配置

3. 沙箱测试账号

• 在支付宝开放平台沙箱环境中获取测试账号
• 使用"沙箱买家"账号进行支付测试
• 注意：沙箱环境有金额限制

4. 生产环境上线

• 申请正式应用（需要审核）
• 配置正式环境的APPID和密钥
• 确保回调地址使用正式域名
• 完成商户资质认证

六、安全检查

1. 密钥安全

   • 私钥绝对不能泄露
   • 生产环境使用环境变量或密钥管理服务
   • 不要将密钥提交到代码仓库

2. 回调验证

   • 所有回调必须验证签名
   • 验证订单金额和状态
   • 防止重复处理

3. HTTPS要求

   • 生产环境必须使用HTTPS
   • 回调地址必须是HTTPS

七、当前项目状态

✅ 代码已实现 ✅ Maven依赖已配置 ⚠️ 需要配置支付宝账号和密钥 ⚠️ 需要配置回调地址（开发环境可用ngrok）

八、快速开始

1. 注册支付宝开放平台账号
2. 创建应用获取APPID
3. 生成密钥对并配置
4. 配置回调地址（开发环境使用ngrok）
5. 更新application-dev.properties配置文件
6. 启动项目测试支付功能

九、参考文档

• 支付宝开放平台：https://open.alipay.com
• 支付宝开发者文档：https://opendocs.alipay.com
• IJPay文档：https://github.com/Javen205/IJPay