支付插件完整功能介绍与使用教程

本文档面向站点管理员、运营人员、商户用户和需要接入支付能力的开发者，基于当前项目代码整理支付插件的全部主要功能。插件提供多渠道支付、支付订单管理、商户平台、结算、提现、通知、安全回调和 API 对接能力。

功能体验

1. 功能总览

支付插件由五类入口组成：

核心业务闭环：

1. 管理员配置支付渠道、回调域名、密钥和允许的支付渠道。

2. 用户或商户通过插件发起支付。

3. 插件创建支付单并跳转到支付渠道或展示二维码。

4. 支付人可通过 /payment/{paymentId} 查看支付状态、继续支付或跳转返回地址。

5. 支付渠道通过公开回调接口通知支付结果。

6. 插件更新订单状态，并按配置发送 Halo 通知。

7. 商户订单进入结算流程，管理员确认结算后入账。

8. 商户发起提现申请，管理员审核并标记打款结果。

2. 安装与启用

2.1 前置条件

• Halo 版本满足 >= 2.25.0

• 已安装并启用 LywqPluginCore >= 2.3.0

• 站点外部访问地址正确，支付渠道回调地址能被公网访问

• 如果要启用商户平台，需要提前准备一个 Halo 角色作为商户角色

2.2 启用插件

1. 在 Halo 控制台安装并启用支付插件。

2. 进入插件设置，先完成“通用设置”。

3. 按需启用支付宝、微信支付、易支付、源支付、虎皮椒、PayPal、Stripe 或自定义支付。

4. 如果需要商户平台能力，再进入“商户平台设置”开启商户平台。

别上来就直接填支付渠道密钥然后开干，回调域名、允许渠道、超时时间没配好，后面查问题能把人查出火星子。

3. 通用设置与支付渠道配置

3.1 通用设置

通用设置决定支付插件的基础运行行为：

推荐配置顺序：

1. 设置支付回调域名，生产环境必须是公网 HTTPS 域名。

2. 生成接口加解密密钥，保存配置后刷新页面确认密钥已生效。

3. 设置订单超时时间，例如 15 分钟。

4. 设置同步任务频率，常规站点用每 1 分钟或每 5 分钟即可。

5. 勾选允许开放的支付渠道。

6. 选择需要接收支付通知的管理员账号。

3.2 支持的支付方式

插件当前注册了 8 类支付服务：

3.3 渠道配置要点

支付宝需要配置 appId、应用私钥、支付宝公钥、签名类型、网关和产品码。微信支付需要配置 appId、商户号、APIv3 密钥、证书序列号和私钥证书。易支付、源支付和虎皮椒主要配置接口地址、商户号和密钥。PayPal 需要 Client ID、Client Secret、Webhook ID 和币种。Stripe 需要 Secret Key、Webhook Secret 和币种。

配置时注意三件事：

1. “支付方式启用”只说明该服务可用。

2. “支持的支付渠道”才决定前端或商户 API 能否选择该渠道。

3. 支付回调域名不通，订单状态就可能卡住，只靠定时同步兜底不是长久办法。

4. 支付订单管理与发起支付

4.1 支付总览

控制台 > 支付管理 > 总览展示：

• 订单总数

• 订单总金额

• 成交总数

• 成交金额

• 每日订单趋势

• 最近成功订单

运营人员可以按日期范围筛选，用来观察站点支付转化和订单异常。

4.2 支付订单列表

控制台 > 支付管理 > 支付订单支持：

• 按订单号、支付单号、平台、状态、支付类型、用户、日期范围筛选

• 按创建时间排序

• 查看支付二维码或支付链接

• 查看订单详情和附加数据

• 编辑订单基础信息和状态

• 删除单条或批量删除订单

• 自动刷新列表

支付状态通常包括待支付、支付中、支付成功、支付失败等状态。订单是否最终成功，以渠道回调、查询结果和插件最终状态为准。

4.3 发起测试支付

控制台 > 支付管理 > 发起支付可用于联调渠道配置。

操作步骤：

1. 选择支付类型，例如支付宝、微信支付、PayPal 或 Stripe。

2. 选择支付渠道，例如支付宝当面付、微信 Native、Stripe Checkout。

3. 填写订单号、标题、金额、通知地址和返回地址。

4. 提交后查看返回的二维码、跳转链接或渠道响应。

5. 完成支付后回到支付订单列表确认状态。

如果发起支付返回“当前支付渠道未启用”，优先检查“通用设置 > 支持的支付渠道”，别只盯着某个渠道的 enabled 开关，俩开关不是一回事。

4.4 前台支付页

插件提供前台支付页：

GET /payment/{paymentId}

这个页面会根据订单状态展示不同内容：

PayPal、Stripe 和自定义支付在进入支付页时会尝试重新查询一次支付状态，减少支付渠道跳回站点后状态没及时刷新的尴尬。这个设计挺实在，支付状态这种东西最怕“用户钱扣了，页面还装死”。

5. 用户中心支付能力

用户中心 > 支付管理面向普通登录用户，主要用于用户查看自己的系统订单。

用户可以：

• 查看自己的支付订单

• 按状态、支付类型、支付渠道和时间筛选

• 继续处理未完成支付

• 关闭未支付订单

• 删除自己的订单记录

• 查看订单详情、二维码、支付链接和附加信息

用户中心接口会自动限制为当前登录用户和系统平台订单，避免用户看到其他人的支付数据。

6. 商户入驻与商户管理

6.1 商户平台设置

启用商户平台前，管理员需要进入插件设置 > 商户平台设置：

6.2 用户申请入驻

用户中心 > 商户平台 > 开通商户：

1. 填写商户名称、联系人、联系电话、联系邮箱。

2. 选择业务类型。

3. 填写商户描述。

4. 阅读并同意协议条款。

5. 提交申请。

如果关闭“是否需要审核”，申请成功后商户会直接进入 ACTIVE 状态。如果开启审核，商户状态为 PENDING，需要管理员处理。

6.3 管理员审核商户

控制台 > 商户管理 > 商户：

1. 查看待审核商户。

2. 打开商户详情，检查主体信息、联系人、业务类型和描述。

3. 选择审核通过或拒绝，并填写审核备注。

4. 审核通过后，插件会同步商户角色，让用户进入商户平台。

5. 对已激活商户可执行启用、停用、编辑资料、配置单独结算费率等操作。

商户状态说明：

7. 商户平台与 API 对接

商户平台是给已入驻商户使用的独立工作台。商户登录用户中心后，可以进入用户中心 > 商户平台。

7.1 商户工作台

商户平台包含：

• 经营概览：订单数、订单金额、成交数、成交金额

• 支付订单：查看、筛选、编辑、关闭和删除商户自己的平台订单

• 结算记录：查看自己的结算单

• 提现管理：维护提现账户、发起提现、查看提现状态

• 接入文档：查看发起支付、查询支付、关闭支付等 API 示例

7.2 商户发起支付

商户可通过平台接口发起支付：

POST /apis/platform.payment.muyin.site/v1alpha1/initiatePayment
Content-Type: application/json

示例请求：

{
  "orderId": "ORDER-20260628-001",
  "subject": "会员套餐",
  "body": "一年期会员套餐",
  "paymentAmount": 99.00,
  "paymentType": "ALIPAY",
  "paymentChannel": "FACE_TO_FACE_PAYMENT",
  "notifyUrl": "https://example.com/pay/notify",
  "returnUrl": "https://example.com/pay/return"
}

常用平台接口：

商户接口会把请求强制绑定到当前登录商户用户名，调用方不能通过传 platform 字段去操作其他商户的数据。这点别绕，绕了也没用。

7.3 加密支付

加密支付使用通用设置中生成的 RSA 密钥。接入方用公钥加密业务请求，插件用私钥解密后发起支付。

推荐用于这些场景：

• 商户系统不希望明文传输完整支付请求

• 需要降低参数被篡改风险

• 接入方和支付站点之间不是同一个系统

8. 结算管理

结算模块把商户成功订单聚合成结算记录，管理员确认后把结算金额计入商户余额。

8.1 结算来源

结算订单需要满足：

• 支付状态为成功

• 订单属于商户平台订单

• 订单尚未被结算标记占用

8.2 自动结算

开启自动结算后，插件会按配置的 Cron 表达式执行结算任务。

配置步骤：

1. 插件设置 > 商户平台设置 > 打开“是否启用自动结算”。

2. 填写结算周期 Cron，例如每月 1 日执行。

3. 填写默认结算手续费率。

4. 保存配置。

自动结算会按商户聚合成功订单，生成待结算记录。

8.3 手动结算

控制台 > 商户管理 > 结算：

• 可按全部商户触发结算

• 可按指定商户触发结算

• 可按指定支付单号触发结算

适合临时补账、测试联调或处理自动结算之外的特殊订单。

8.4 结算审核

管理员可对待结算记录执行：

结算金额计算逻辑：

结算金额 = 成功订单总额 - 结算手续费
结算手续费 = 成功订单总额 × 结算手续费率

商户单独配置了结算费率时，优先使用商户费率；否则使用系统默认费率。

9. 提现管理

提现模块把商户余额从平台侧流转到商户收款账户，支持银行卡、支付宝和微信账户信息。

9.1 商户维护提现账户

用户中心 > 商户平台 > 提现管理：

1. 添加提现账户。

2. 选择账户类型：银行卡、支付宝或微信。

3. 填写账户名称、账号、开户行或收款码信息。

4. 设置默认提现账户。

9.2 商户申请提现

商户申请提现时，系统会校验：

• 商户必须为 ACTIVE

• 提现金额必须大于 0

• 提现金额不能超过可提现余额

• 选择的提现账户必须存在

提交成功后：

• 生成提现记录

• 状态变为 PENDING_AUDIT

• 对应金额计入冻结金额

9.3 管理员审核提现

控制台 > 商户管理 > 提现：

1. 查看待审核提现记录。

2. 按申请时间倒序查看最新提现申请。

3. 打开详情，核对商户、账户、金额、申请备注。

4. 审核通过或拒绝。

5. 通过后可标记处理中。

6. 打款成功后标记完成，填写打款流水号或备注。

7. 打款失败时标记失败，填写失败原因。

提现状态说明：

9.4 批量操作

提现审核页面支持批量审核和批量打款状态流转。批量操作只处理状态符合条件的记录，不符合条件的记录会跳过。

10. 通知、安全与回调

10.1 异步回调

公开回调接口：

/apis/public.payment.muyin.site/v1alpha1/asyncCallback/{paymentType}

支持的 paymentType 包括：

• ALIPAY

• WECHATPAY

• EPAY

• YPAY

• HUPIJIAO

• CUSTOM

PayPal 和 Stripe 的 Webhook 会通过 CUSTOM 入口，根据请求头识别并交给对应服务处理。

10.2 签名与校验

插件针对不同渠道使用不同安全机制：

10.3 支付通知

插件内置 Halo 通知模板。支付状态变化后可通知配置的用户，通知内容包含：

• 订单标题

• 支付单号

• 订单号

• 支付金额

• 支付状态

• 继续支付或查看详情入口

11. 权限说明

插件声明了四类权限模板：

商户平台角色需要在插件设置中配置。商户审核通过后，插件会把对应角色授予商户用户；商户停用或拒绝后，应注意检查角色同步结果。

12. 推荐上线流程

12.1 单站点自用支付

1. 配置通用设置。

2. 启用至少一个支付渠道。

3. 在“支持的支付渠道”中勾选该渠道。

4. 使用“发起支付”测试创建订单。

5. 完成真实支付或沙箱支付。

6. 检查支付订单状态和通知。

7. 确认回调地址无误。

12.2 开放商户平台

1. 先完成单站点支付配置。

2. 创建商户角色。

3. 启用商户平台。

4. 开启商户入驻，并配置业务类型、协议条款和开通须知。

5. 根据业务决定是否开启商户审核。

6. 配置结算手续费率和自动结算周期。

7. 用测试用户提交商户入驻申请。

8. 管理员审核通过。

9. 商户进入商户平台发起测试订单。

10. 管理员触发结算并确认入账。

11. 商户维护提现账户并申请提现。

12. 管理员完成提现审核和打款标记。

13. 常见问题

13.1 支付渠道已经启用，为什么发起支付仍提示渠道未启用？

检查“通用设置 > 支持的支付渠道”是否勾选了对应渠道。渠道配置里的启用开关和允许渠道白名单都要满足。

13.2 为什么支付成功后订单状态没有更新？

优先检查：

1. 支付回调域名是否公网可访问。

2. 渠道后台配置的回调地址是否正确。

3. Webhook Secret、Webhook ID、签名密钥是否匹配。

4. 同步定时任务是否启用。

13.3 商户为什么看不到商户平台？

检查：

1. 商户平台是否启用。

2. 商户是否为 ACTIVE 状态。

3. 商户角色是否已授予该用户。

4. 用户是否重新登录或刷新权限。

13.4 结算记录为什么没有生成？

常见原因：

• 没有成功支付的商户订单

• 订单已经被其他结算记录标记

• 商户平台或结算功能未启用

• 自动结算 Cron 未触发

• 手动结算时商户用户名或支付单号填写错误

13.5 提现为什么失败？

常见原因：

• 商户不是 ACTIVE

• 可提现余额不足

• 提现账户不存在或信息不完整

• 管理员拒绝提现

• 打款失败后被标记为 FAILED