跳到主要内容

WebShopX-Payments 服主文档

This plugin is based on SweetCheckout, licensed under AGPL-3.0.

问题反馈​

本目录面向插件安装者、运维与后台管理员，详细介绍 WebShopX-Payments 支付集成插件的部署与配置。

阅读地图
  1. 安装与部署
  2. 配置文件详解
  3. 官方支付通道配置
  4. Hook 支付通道配置
  5. 命令与权限体系
  6. 常见问题与排障

一眼看懂 WebShopX-Payments 职责​

WebShopX-Payments（又称 WSXPay）是 WebShopX 的专属支付 Provider（底层服务提供者）插件。

核心职责界定
  • WebShopX：负责核心业务，包括玩家账户余额、充值订单管理、商品展示与购买逻辑、兑换码以及发货（玩家领取/充值命令执行）。
  • WebShopX-Payments：专注于支付链路本身，包括请求内嵌支付后端创建支付、轮询/接收回调支付状态、匹配 Hook 收款通知，最终将成功的支付状态上报回 WebShopX。

核心系统拓扑​

组件说明
Bukkit 插件端 (WSXPay)作为 WebShopX 的 webshopx-payments provider 运行，管理指令及支付状态上报。
内嵌后端 (with-backend)集成于插件内的轻量级服务（默认端口 62233），直接与支付宝、微信、PayPal、MercadoPago 等上游服务对接。
外部 Hook 辅助端 (可选)运行在本地或特定 Windows 系统的独立可执行程序（v3/v4），用于在不接入官方企业接口时抓取个人收款通知并转发给内嵌后端。

你最需要先关心的风险点​

高危配置与防坑提醒
  1. 不要暴露内嵌后端端口：默认的 62233 端口仅用于 Bukkit 插件与后端之间的 WebSocket/HTTP 通信。Hook 终结点路径（/api/hook/receive）并无安全校验，请勿将后端端口直接暴露到公网！
  2. Hook 模式的金额竞争冲突：所有 Hook 模式（支付宝/微信 Hook）均依赖 “付款金额” 进行订单匹配。同一时间段内，不能有两名玩家同时创建相同金额的 Hook 订单（例如不能同时创建两个 1.00 元的微信扫码订单）。后面发起的玩家必须等待前面的订单支付完成或超时取消。官方接口（WeChat Native、Alipay 订单码等）则完全无此限制。
  3. 私钥凭证安全：请勿将包含生产密钥、商户私钥、Client Secret 的配置文件或 secrets 密钥文件夹上传至公开代码库。

运维节奏建议​

  1. 先确保 WebShopX 本身部署就绪，能够正常访问管理后台。
  2. 安装 WebShopX-Payments 并选择合适的支付通道（先建议配置 PayPal 沙盒或微信/支付宝经营收款码进行小额测试）。
  3. 玩家进行测试支付，并在扫码支付后游戏内能够瞬时收到 WebShopX 的入账与发货命令通知。
  4. 在生产环境正式上线。

免责声明与使用条款​

法律告知

本项目仅供学习研究与技术交流之用，请勿用于任何非法用途。因违反法律法规或滥用本项目造成的任何后果，由使用者自行承担。

  1. 无担保声明
    本项目作者与贡献者不对本项目的有效性、可靠性、安全性作任何明示或暗示的保证。亦不对因使用或滥用本项目所造成的任何直接、间接损失、责任、索赔或诉讼承担任何法律责任。

  2. 版权与合规
    本项目的源代码及二进制文件的使用者，应严格遵守当地法律法规，尊重腾讯（Tencent）公司、阿里巴巴（Alibaba）集团及其他第三方的版权与隐私权益，不得从事任何侵害他人合法权益或违背公序良俗的行为。

  3. 接受条款
    使用或保留本项目的任何部分（包括源码或编译文件），即视为您已阅读并完全同意本声明的所有条款。如有异议，请立即停止使用并彻底删除所有相关文件。

💡 关于“无费率”的补充说明

项目简介中所提及的“无费率”，是指本项目绝不额外收取任何中间手续费或平台抽成。

  • 示例：如您使用支付宝官方的“当面付/订单码支付”接口，支付宝官方会正常收取 0.6% 的商户手续费（最终费率即为 0.6%），本项目作为开源工具，中间不会产生任何额外的二次抽成或隐形费用。