支付宝支付接入

本页说明 RuoYi Office 中如何用 Pay 模块接入支付宝支付，并以当前仓库的“示例订单”链路作为最小可运行参考。示例订单不是生产业务模型，而是帮助你确认支付应用、渠道、收银台、支付回调和业务单状态更新是否跑通。

如果尚未配置支付应用和渠道，请先阅读 支付功能开启。

当前实现边界

层	路径 / 接口
示例订单控制器	yudao-module-pay-server/src/main/java/.../controller/admin/demo/PayDemoOrderController.java
示例订单服务	service/demo/PayDemoOrderServiceImpl.java
支付订单控制器	controller/admin/order/PayOrderController.java
管理端示例页	apps/web-antd/src/views/pay/demo/order
管理端支付订单页	apps/web-antd/src/views/pay/order
收银台页面	apps/web-antd/src/views/pay/cashier
示例订单接口	/admin-api/pay/demo-order/*
支付订单接口	/admin-api/pay/order/*

示例订单服务中固定使用：

private static final String PAY_APP_KEY = "demo";

因此管理后台「支付应用」中需要存在 appKey = demo 的应用，并配置可用的支付宝渠道，例如 alipay_pc、alipay_wap、alipay_qr、alipay_app 或 alipay_bar。

支付链路

这个链路体现生产接入的关键原则：业务单先创建 Pay 支付单，用户在收银台选择渠道提交支付，Pay 模块回调业务系统更新业务单状态。

第一步：配置支付宝渠道

在「支付管理 -> 支付应用」中找到 demo 应用，点击支付宝渠道配置按钮。不同支付宝渠道的字段基本一致：

字段	说明
应用 ID	支付宝开放平台应用的 AppId
网关地址	沙箱或生产网关地址
签名方式	当前前端默认使用 RSA2
应用私钥	商户应用私钥，严禁提交到代码仓库
支付宝公钥 / 证书	与应用签名模式匹配
加密配置	如开启接口内容加密，需要配置加密算法和密钥

本地联调建议先使用沙箱环境。真实生产环境需要公网回调地址、正式应用、正式商户能力和证书/密钥安全管理。

第二步：创建示例订单

管理端入口通常是「支付管理 -> 支付示例 -> 示例订单」。页面会调用：

POST /pay/demo-order/create
GET  /pay/demo-order/page

创建订单时，PayDemoOrderServiceImpl#createDemoOrder 会做三件事：

1. 根据示例商品编号生成本地示例订单。
2. 调用 PayOrderApi#createOrder 创建 Pay 支付单。
3. 把 payOrderId 回写到示例订单。

示例商品价格以“分”为单位，例如 1、10、100 等，方便在沙箱中低成本测试。

第三步：前往收银台支付

示例订单列表的“前往支付”按钮会跳转：

router.push({
  name: 'PayCashier',
  query: {
    id: row.payOrderId,
    returnUrl: encodeURIComponent(`/pay/demo/order?id=${row.id}`),
  },
});

收银台根据 payOrderId 查询支付单，并提交：

POST /pay/order/submit

提交时需要传入渠道编码。支付宝常见编码如下：

渠道编码	场景
alipay_pc	PC 网站支付
alipay_wap	手机网站支付
alipay_app	App 支付
alipay_qr	扫码支付
alipay_bar	条码支付

第四步：确认业务回调

支付宝支付成功后，Pay 模块会把支付结果通知给示例订单：

POST /pay/demo-order/update-paid

该接口由 Pay 模块内部回调，无需登录，安全校验在业务服务内部完成。updateDemoOrderPaid 会校验：

• 示例订单是否存在。
• 示例订单是否已经支付，重复回调要幂等处理。
• Pay 支付单是否存在且状态成功。
• 支付金额是否和示例订单一致。
• merchantOrderId 是否等于示例订单 ID。

如果任一校验失败，说明支付单和业务单不匹配，不能直接把业务单改为已支付。

生产业务接入要点

事项	建议
appKey	每类业务使用明确的支付应用标识，不要全部复用 demo
merchantOrderId	使用业务单主键或稳定业务单号，必须唯一且可反查
notifyUrl	业务回调地址要可被 Pay 模块访问，并能幂等处理
金额	后端统一以分传输和存储，回调时必须校验金额
状态	业务单更新要基于原状态条件更新，避免重复回调造成脏写
日志	支付成功、失败、回调异常都要保留足够日志便于对账

排查清单

现象	优先检查
收银台看不到支付宝渠道	demo 应用下支付宝渠道是否启用，渠道编码是否匹配
支付提交失败	支付宝应用 ID、私钥、公钥/证书、网关地址是否正确
支付成功但示例订单未更新	PayNotifyJob、/pay/demo-order/update-paid 日志、支付单状态
回调金额不匹配	示例订单价格和 Pay 支付单 price 是否一致
重复回调报错	业务回调是否按支付单编号做幂等判断

下一步

支付跑通后，可以继续验证 退款接入；如果要查看全部支付订单，请进入管理端「支付订单」页面。