zyt/admin/PAYMENT_GATEWAY_INTEGRATION.md

支付网关集成指南

概述

本文档说明如何配置和集成支付宝和微信支付网关。

环境配置

1. 配置文件

在 .env 文件中添加以下配置：

# 支付宝配置
ALIPAY_APP_ID=your_app_id
ALIPAY_MERCHANT_PRIVATE_KEY=your_merchant_private_key
ALIPAY_PUBLIC_KEY=your_alipay_public_key
ALIPAY_NOTIFY_URL=https://yourdomain.com/api/order/alipay-notify
ALIPAY_RETURN_URL=https://yourdomain.com/order
ALIPAY_GATEWAY_URL=https://openapi.alipay.com/gateway.do

# 微信支付配置
WECHAT_APP_ID=your_app_id
WECHAT_MCH_ID=your_mch_id
WECHAT_API_KEY=your_api_key
WECHAT_NOTIFY_URL=https://yourdomain.com/api/order/wechat-notify
WECHAT_GATEWAY_URL=https://api.mch.weixin.qq.com

2. 数据库迁移

运行以下SQL添加 trade_no 字段到订单表：

ALTER TABLE `la_order` ADD COLUMN `trade_no` varchar(100) DEFAULT NULL COMMENT '第三方交易号' AFTER `payment_time`;

支付流程

正常支付流程

1. 用户点击"支付"按钮
2. 选择支付方式（支付宝或微信）
3. 点击"确认支付"
4. 前端调用 /order.order/alipay 或 /order.order/wechat 接口
5. 后端生成支付链接/数据并返回
6. 前端跳转到支付页面或显示二维码
7. 用户完成支付
8. 支付网关回调 /api/order/alipay-notify 或 /api/order/wechat-notify
9. 后端验证签名并更新订单状态

补单支付流程

1. 用户选择"补单支付"
2. 输入支付订单号
3. 选择支付方式
4. 点击"确认支付"
5. 前端调用支付接口，参数中 is_supplement=1
6. 后端不校验订单是否存在，直接生成支付链接/数据
7. 用户完成支付
8. 支付网关回调更新订单状态

支付宝集成

获取密钥

1. 登录 支付宝开放平台
2. 进入"开发者中心" -> "应用管理"
3. 创建应用或选择已有应用
4. 在"应用信息"中获取 App ID
5. 在"开发设置"中生成密钥对
6. 下载商户私钥和支付宝公钥

配置回调

1. 在应用设置中配置"异步通知地址"
2. 地址格式：https://yourdomain.com/api/order/alipay-notify
3. 配置"同步返回地址"（可选）
4. 地址格式：https://yourdomain.com/order

测试

支付宝提供沙箱环境用于测试：

• 沙箱网址：https://openapi.alipaydev.com/gateway.do
• 在 .env 中设置 ALIPAY_GATEWAY_URL=https://openapi.alipaydev.com/gateway.do

微信支付集成

获取密钥

1. 登录 微信商户平台
2. 进入"账户中心" -> "API安全"
3. 获取商户号（Mch ID）
4. 在"API密钥"中生成 API Key
5. 在"证书管理"中下载证书（如需要）

配置回调

1. 在商户平台配置"回调地址"
2. 地址格式：https://yourdomain.com/api/order/wechat-notify

测试

微信支付提供沙箱环境用于测试：

• 沙箱网址：https://api.mch.weixin.qq.com
• 使用测试商户号和 API Key

后端实现

支付逻辑（OrderLogic.php）

• alipayPay() - 生成支付宝支付URL
• wechatPay() - 生成微信支付数据
• generateAlipayUrl() - 生成支付宝支付链接
• generateWechatPayData() - 生成微信支付数据
• generateAlipaySign() - 生成支付宝签名
• generateWechatSign() - 生成微信签名

回调处理

• AlipayNotifyController::notify() - 处理支付宝异步通知
• WechatNotifyController::notify() - 处理微信异步通知

签名验证

• 支付宝：使用 RSA2 算法验证签名
• 微信：使用 MD5 算法验证签名

前端实现

支付流程

1. 用户选择支付方式
2. 调用 alipayPay() 或 wechatPay() API
3. 获取支付链接或支付数据
4. 支付宝：跳转到支付页面
5. 微信：显示二维码或其他处理

支付状态更新

• 支付完成后，后端通过回调更新订单状态
• 前端定时刷新订单列表以获取最新状态

常见问题

1. 签名验证失败

• 检查密钥是否正确
• 检查签名算法是否匹配
• 检查参数排序是否正确

2. 回调未收到

• 检查回调地址是否正确
• 检查防火墙是否允许回调
• 检查日志中是否有错误信息

3. 金额不匹配

• 检查前端传递的金额是否正确
• 检查后端计算的金额是否正确
• 微信支付需要将金额转换为分

安全建议

1. 不要在代码中硬编码密钥，使用环境变量
2. 验证所有回调请求的签名
3. 使用 HTTPS 传输敏感信息
4. 定期更新密钥
5. 记录所有支付相关的日志
6. 实现幂等性处理，防止重复支付

测试清单

• 支付宝支付流程测试
• 微信支付流程测试
• 补单支付流程测试
• 回调处理测试
• 签名验证测试
• 金额验证测试
• 异常处理测试
• 并发支付测试