跳到主内容
版本: 1.x

网关模板

网关模板为您提供了构建您自己仅限 POS 的支付网关的起始点。它生成一个可工作的 WordPress 插件，包含一个可以安装和自定义以满足您需求的 PHP 文件。

功能​

最少代码

仅一个 PHP 文件，包含必要内容 - 易于阅读和修改

仅限 POS

默认在网页结账时禁用，可以通过 WCPOS 设置启用

自动化设置

一个 shell 脚本为您处理所有占位符替换

GitHub 发布

推送版本更新，GitHub Actions 会生成可下载的 ZIP

开始使用​

1

克隆模板库

git clone https://github.com/wcpos/woocommerce-gateway-template.git
cd woocommerce-gateway-template

或者点击 GitHub 仓库 上的 使用此模板 按钮来创建您自己的副本。

2

运行设置脚本

./create-gateway.sh

脚本会要求您输入一些细节 - 您的网关名称、简短描述及您的 GitHub 用户名 - 然后在您选择的目录中生成一个可用的插件。

3

安装插件

您有两个选择：

选项 A — 直接复制文件夹（如果您有服务器访问权限）： 将生成的网关文件夹复制到您网站的 wp-content/plugins/ 目录中。

选项 B — 压缩上传（对大多数人来说最简单）：

  1. 将生成的文件夹压缩成 .zip 文件
  2. 在 WordPress 中，转到 插件 > 添加新 > 上传插件
  3. 选择 zip 文件并点击 立即安装
4

在 WCPOS 中启用

  1. 转到 WP 管理 > WCPOS > 设置 > 结账
  2. 在列表中找到您的新网关并启用它
注意

网关在常规网页结账时默认禁用。WCPOS 控制哪些网关在 POS 中显示，通过其自己的设置进行管理。

手动设置​

如果您不想使用脚本，可以自己替换占位符。打开每个文件并查找和替换以下内容：

占位符输入的内容示例
{{GATEWAY_NAME}}您网关的显示名称现金支付
{{GATEWAY_SLUG}}URL 安全标识符（小写，连字符）cash-payment
{{GATEWAY_DESCRIPTION}}网关的简短描述在 WCPOS 中接受现金支付
{{GATEWAY_DEFAULT_DESCRIPTION}}在结账时显示给收银员的文本在销售点用现金支付
{{GITHUB_USERNAME}}您的 GitHub 用户名kilbot
{{REPO_NAME}}您的仓库名称cash-payment-gateway
{{AUTHOR_NAME}}您的名字kilbot
{{GATEWAY_ID}}使用下划线替代连字符的缩写cash_payment
{{GATEWAY_CLASS_NAME}}每个单词首字母大写，用下划线连接Cash_Payment
{{GATEWAY_FUNCTION_PREFIX}}与网关 ID 相同cash_payment

然后将 wcpos-{{GATEWAY_SLUG}}.php 重命名以匹配您的缩写（例如，wcpos-cash-payment.php）。

提示

设置脚本会根据名称和缩写自动推导 GATEWAY_ID、GATEWAY_CLASS_NAME 和 GATEWAY_FUNCTION_PREFIX，因此在手动设置时您只需考虑这些信息。

工作原理​

生成的插件注册了一个 WooCommerce 支付网关类。以下是您需要了解的关键内容：

  • $this->enabled = 'no' — 网关在网页结账时是隐藏的。WCPOS 基于您的 POS 设置在 POS 中启用它。
  • process_payment() — 调用 $order->payment_complete()，标记订单为已支付并自动处理库存减少。
  • init_form_fields() — 定义在 WooCommerce 设置中显示的标题和描述字段。

自定义您的网关​

添加支付字段​

如果您的网关需要收银员输入（例如，参考编号），可以覆盖 payment_fields() 方法：

public function payment_fields() {
    if ( $this->description ) {
        echo wpautop( wptexturize( $this->description ) );
    }

    woocommerce_form_field( 'my_gateway_reference', array(
        'type'        => 'text',
        'label'       => __( 'Reference Number', 'your-text-domain' ),
        'required'    => true,
    ) );
}

您可以通过 $_POST['my_gateway_reference'] 在 process_payment() 中读取提交的值。请记得使用 sanitize_text_field() 清理任何输入。

更改支付行为​

默认模板会立即将订单标记为已支付。如果您的工作流程要求稍后支付（如发票），则可以将 payment_complete() 替换为状态更新：

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // Set to pending — the customer will pay later.
    $order->update_status( 'pending', __( 'Awaiting payment', 'your-text-domain' ) );

    // Stock must be reduced manually when not using payment_complete().
    wc_reduce_stock_levels( $order_id );

    return array(
        'result'   => 'success',
        'redirect' => $this->get_return_url( $order ),
    );
}

修改和更新​

安装网关后，您可以继续编辑插件文件以调整支付逻辑。要安装更新版本：

  1. 编辑生成文件夹中的 wcpos-your-slug.php
  2. 更新插件头中的 Version: 号码（例如，0.1.0 到 0.2.0）
  3. 压缩文件夹并通过 插件 > 添加新 > 上传插件 重新上传，或者直接替换 wp-content/plugins/ 中的文件夹
提示

当您上传具有相同插件名称的 ZIP 时，WordPress 会询问您是否要替换现有插件 - 点击 用上传的替换当前 进行更新。

使用 GitHub 进行自动发布​

如果您将网关推送到 GitHub 仓库，模板包括一个 GitHub Actions 工作流程，可自动创建发布：

  1. 更新插件头中的 Version: 号码
  2. 提交并推送到 main 分支
  3. GitHub Actions 检测到版本更改并创建一个新发布，提供可下载的 ZIP

其他用户可以从您的仓库 发布 页面下载 ZIP，并像任何 WordPress 插件一样安装。

故障排除​

网关未在 POS 显示
  • 检查插件是否在 WP 管理 > 插件 中激活
  • 转到 WP 管理 > WCPOS > 设置 > 结账，确保网关已启用
  • 确保已安装并激活 WooCommerce
网关在网页结账中显示
  • 确保在网关构造函数中设置了 $this->enabled = 'no';
  • WCPOS 会覆盖此设置以适用于 POS 请求，因此网关应仅在 POS 中出现
订单保持在'处理中'而不是'完成'
  • WooCommerce 根据产品类型设置订单状态。包含实物产品的订单保持在 "处理中" — 这是 WooCommerce 的正常行为。只有包含完全虚拟或可下载产品的订单才会自动标记为 "完成"。

资源​

示例网关​

这些现有网关采用相同的方法构建，是很好的参考：