Drupal Commerce 接入 Paymos

安装前确认

运行 composer require drupal/commerce_paymos:^1.0 安装 1.0.0 稳定版，再将商店连接到 Paymos 并添加支付网关。

需要 Drupal ^10.3 || ^11、Commerce ^3。模块要求 PHP ^8.1；若 Drupal 要求更高版本，以 Drupal 为准。商店须有公开可访问的 HTTPS 地址。

模块添加原生外部付款方式。顾客跳转到付款页，订单和付款记录仍留在 Drupal Commerce。

安装前请一并核对三项版本要求。模块声明的最低版本，不能替代当前 Drupal 版本自身的要求。

安装模块

优先用 Composer。Drupal.org 发布版本后，在 Drupal 项目目录运行：

composer require 'drupal/commerce_paymos:^1.0'

也可从 GitHub 版本页获取手动安装 ZIP，其中已包含 PHP SDK。将 commerce_paymos 目录放入第三方模块目录，再到 Drupal 启用模块。保留包内 SDK 文件。模块许可证为 GPL-2.0-or-later，SDK 为 MIT。

连接商店

先打开 Paymos 控制台，选好商店要用的项目。再到 Drupal 打开 /admin/commerce/config/payment/paymos，点击 Connect Paymos。打开确认链接，批准当前项目的连接。回到 Drupal，点击 Check approval。

接着打开 /admin/commerce/config/payment-gateways/add，新建付款方式，选择 Paymos，再选 Sandbox 或 Live。连接商店和新建付款方式是两步，均需完成。

确认页面沿用控制台当前选中的项目，没有另一个项目选择步骤。点击连接按钮前请先核对项目。

凭据加密存入 Drupal state，由 Drupal 私钥和 hash_salt 保护，不进入配置导出。商店规范网址变更后，须重新连接。连接时会自动登记 /paymos/webhook，无需手动登记 webhook，也无需输入密钥。

在现有 Paymos 项目中设置一次：把 Drupal 后台显示的 /paymos/return 地址填入 Success URL，把 /paymos/return?cancel=1 地址填入 Fail URL。买家点击付款页上的 Back to store 返回商店。

返回目标保存在同一浏览器会话中，一小时后过期，只用于最近一次 Paymos 付款流程。会话数据缺失、过期，或订单与支付网关不再匹配时，打开商店首页。买家返回不代表付款成功。付款状态以核验后的 webhook/API 数据及 Drupal Commerce 付款记录为准。

更新模块后，重建 Drupal 缓存：drush --uri=https://your-store.example cache:rebuild。

核对付款

收到带签名的通知后，还会通过 API 反查。账单须与订单、项目、环境、金额和币种一致，SQL 事务才写入一笔已完成的 Commerce 付款。重复通知不会再记一笔。

不足额、逾期或数据不符的付款均不会自动发货。数据不符时需人工核查。订单履约由商店的 Commerce 流程决定，模块不自动退款。

付款核对完成后，仍由商店原有流程决定如何履约；请结合自己的订单流程检查发货安排。

设置定时任务

保持 Drupal cron 定期运行。任务分批核对未解决的账单，每批数量有限。使用 Drush 时，须传入商店的规范 HTTPS 网址，将示例域名换成商店地址：

drush --uri=https://your-store.example cron

通知正常到达时，也请保留定时任务，让未解决的账单继续接受核对。

卸载模块

先处理未解决的账单。只要还有此类账单，模块就不允许卸载。卸载会清除本地加密凭据及连接数据，保留 Commerce 原生付款记录。

其他平台可参阅 WooCommerce 接入指南；全部接入方式见插件目录。