简介
本文件面向支付系统集成开发者，提供完整的支付API参考与实现说明。内容覆盖：
- 支付发起：支付方式选择、金额校验、订单绑定、混合支付（余额+网关）、线下凭证上传、货到付款
- 支付状态查询：轮询/主动查询、回调处理、幂等性保证
- 支付失败处理：重试机制、错误码定义、用户提示
- 退款能力：部分退款、全额退款、分账到各支付腿
- 日志与审计：回调原文留底、支付记录展示
- 安全最佳实践：签名验证、幂等、对账兜底
项目结构
支付相关代码按“控制器-服务-插件”分层组织：
- 前台/API 控制器负责参数校验、路由与响应
- 收银台服务封装订单与支付台账交互
- 支付服务统一维护支付台账、状态机、退款与对账
- 支付插件以 Provider/Service 形式接入微信、支付宝、银行转账等渠道
graph TB
subgraph "前端/小程序"
UI["收银台页面"]
end
subgraph "Web/API层"
FC["前台控制器 CashierController"]
AC["API控制器 CashierController"]
CS["收银台服务 CashierService"]
end
subgraph "核心服务"
PS["支付服务 PaymentService"]
OST["订单状态机 OrderStatusTransition"]
end
subgraph "支付插件"
WX["微信支付 WxpayProvider"]
ALI["支付宝 AlipayProvider"]
BANK["银行转账 BankpayProvider"]
end
UI --> FC
UI --> AC
FC --> CS
AC --> CS
CS --> PS
PS --> OST
FC --> WX
FC --> ALI
FC --> BANK
AC --> WX
AC --> ALI
AC --> BANK核心组件
- 支付服务 PaymentService：创建支付台账、推进成功/失败/关闭、合并多腿支付、退款分账、回调留底、离线凭证附件
- 收银台服务 CashierService：获取订单、混合支付拆分、线下凭证保存、货到付款提交
- 前台/API 控制器：收银台入口、发起支付、上传凭证、货到付款
- 支付插件 Provider：统一 start/notify/finish/query/status 接口，屏蔽渠道差异
架构总览
支付流程从收银台发起，经服务层创建支付台账并调起具体支付插件；支付完成后通过回调或轮询确认，最终由支付服务推进订单状态。
sequenceDiagram
participant U as "用户"
participant F as "前台控制器"
participant S as "收银台服务"
participant P as "支付服务"
participant G as "支付插件(微信/支付宝/银行)"
participant O as "订单状态机"
U->>F : 选择支付方式并提交
F->>S : 校验订单与金额
S->>P : 创建支付台账(PENDING)
F->>G : 调用start生成支付表单/链接
G-->>U : 返回支付页面/二维码
G-->>F : 异步通知/回调
F->>P : markSucceeded(payment_sn, transaction_id)
P->>O : changeStatus(PAID)
O-->>P : 成功
P-->>F : 返回结果
F-->>U : 跳转订单页详细组件分析
支付发起接口（收银台）
- 入口：前台/小程序收银台页面
- 关键步骤
- 校验登录态与订单归属
- 可选使用余额抵扣，计算网关应收金额
- 创建支付台账（PENDING），写入过期时间
- 调起支付插件 start，返回第三方HTML/链接
- 返回值：包含订单信息、默认支付方式、支付表单HTML
flowchart TD
Start(["进入收银台"]) --> CheckLogin["校验登录态"]
CheckLogin --> LoadOrder["加载待付款订单"]
LoadOrder --> WalletSplit{"是否使用余额?"}
WalletSplit -- 是 --> Split["计算余额抵扣与网关剩余"]
WalletSplit -- 否 --> CreatePay["创建支付台账(PENDING)"]
Split --> CreatePay
CreatePay --> CallProvider["调用插件start()"]
CallProvider --> Render["渲染支付表单/跳转"]
Render --> End(["等待支付结果"])支付方式集成
- 微信支付
- 支持扫码Native与移动端JSAPI/H5
- 提供 start/notify/finish/query/status 能力
- 支付宝
- 电脑网站支付
- 提供 start/notify/finish/query 能力
- 银行转账
- 网银支付
- 提供 start/notify/finish 能力
classDiagram
class WxpayProvider {
+pluginId()
+meta()
+start(request)
+notify(payload)
+finish(payload)
+status(payload)
+query(request)
}
class AlipayProvider {
+pluginId()
+meta()
+start(request)
+notify(payload)
+finish(payload)
+query(request)
}
class BankpayProvider {
+pluginId()
+meta()
+start(request)
+notify(payload)
+finish(payload)
}支付状态查询与回调处理
- 轮询/主动查询
- 微信支付支持 status 轮询与 query 查询
- 支付宝支持 query 查询
- 回调处理
- 插件 notify/finish 接收第三方通知
- 支付服务 markSucceeded 幂等推进，记录 transaction_id 与 raw_callback
- 订单状态机确保仅合法迁移生效
sequenceDiagram
participant G as "支付插件"
participant C as "控制器"
participant P as "支付服务"
participant O as "订单状态机"
G->>C : 回调(含交易号/金额/签名)
C->>P : markSucceeded(payment_sn, transaction_id, raw_callback)
P->>P : 幂等检查/状态机校验
P->>O : changeStatus(PAID)
O-->>P : 成功
P-->>C : 返回成功
C-->>G : 返回确认支付失败处理
- 失败/关闭标记
- 支付服务提供 markFailed/markClosed，内部进行状态迁移校验并记录原因
- 重试机制
- 未成功的支付保持 PENDING，允许客户端重试或后台对账兜底
- 错误码与提示
- 控制器使用统一错误码返回业务异常，如未找到订单、参数非法、未登录等
退款接口（部分/全额）
- 退款分账
- 按成功支付腿（gateway优先，wallet在后）拆分退款金额
- wallet 腿同步退回余额并落库 succeeded
- gateway 腿登记 pending，待人工或回调收尾
- 收尾退款
- 提供 markRefundSucceeded 完成网关退款收尾，更新支付腿状态为 REFUNDED/PARTIAL_REFUNDED
flowchart TD
RStart["发起退款"] --> QueryLegs["查询成功支付腿"]
QueryLegs --> Allocate{"分配退款金额"}
Allocate --> |wallet腿| RefundWallet["退回余额并落库 succeeded"]
Allocate --> |gateway腿| RefundPending["登记 pending 退款申请"]
RefundWallet --> UpdateLeg["更新支付腿状态"]
RefundPending --> WaitFinish["等待人工/回调收尾"]
WaitFinish --> FinishRefund["markRefundSucceeded 收尾"]
UpdateLeg --> REnd["完成"]
FinishRefund --> REnd线下付款与货到付款
- 线下付款
- 收银台页面生成 offlinepay 支付台账，用户上传凭证后订单进入 awaiting_confirmation
- 后台审核通过后标记支付成功并推进订单
- 货到付款
- 直接标记支付成功并推进订单状态
支付日志与审计
- 回调原文留底：支付服务 recordCallback 记录原始回调内容
- 支付记录展示：后台订单视图显示支付流水、方式、金额、状态、第三方流水号、支付时间
依赖关系分析
- 控制器依赖服务：前台/API 控制器依赖 CashierService 与 PaymentService
- 服务依赖核心：CashierService 依赖 PaymentService 与订单状态机
- 插件解耦：所有支付渠道通过 Provider 接口统一接入，便于扩展
graph LR
FC["前台控制器"] --> CS["收银台服务"]
AC["API控制器"] --> CS
CS --> PS["支付服务"]
PS --> OST["订单状态机"]
FC --> WX["微信支付"]
FC --> ALI["支付宝"]
FC --> BANK["银行转账"]
AC --> WX
AC --> ALI
AC --> BANK性能与可靠性
- 幂等性
- 支付服务 markSucceeded 对已成功的 payment 直接返回 true，避免重复联动
- DB 层唯一键保障相同 (gateway, transaction_id) 不重复落库
- 并发安全
- 钱包支付使用事务与行锁防止超扣
- 对账兜底
- 未推进的订单可由对账任务扫描补齐，避免不可逆终态错配
- 容差处理
- 金额比较使用容差避免浮点误差导致误判
故障排查指南
- 常见问题
- 订单不存在或状态不符：检查订单状态是否为待付款
- 余额不足：混合支付时余额扣减失败将返回错误
- 回调未到达：查看 raw_callback 留底与支付平台通知配置
- 退款未完成：检查 order_refund 状态是否为 pending，需人工或回调收尾
- 建议操作
- 核对 payment_sn 与 transaction_id
- 查看后台订单支付记录与凭证
- 使用查询接口主动确认支付状态
结论
本支付体系通过统一的服务与插件化设计，实现了多渠道支付、混合支付、退款分账与完善的幂等与对账机制。开发者可基于提供的接口快速集成微信、支付宝、银行转账等渠道，并通过查询与回调机制确保支付结果的准确性与一致性。
附录：API参考
- 收银台入口
- 获取收银台订单：返回订单信息与默认支付方式
- 发起支付：创建支付台账并调起支付插件
- 上传线下凭证：关联支付台账并推进订单至待确认
- 货到付款：直接标记支付成功
- 支付插件接口
- start：生成支付表单/链接
- notify/finish：处理第三方回调
- query/status：主动查询支付状态
- 支付服务接口
- createForOrder：创建支付台账
- markSucceeded：推进成功并联动订单
- refundOrder：退款分账
- markRefundSucceeded：收尾网关退款
- recordCallback：记录回调原文