跳到主内容
版本: 1.x

网关模板

网关模板为您构建仅供 POS 使用的自定义支付网关提供起点。它会生成一个仅包含一个 PHP 文件的可用 WordPress 插件，供您安装并按需自定义。

功能​

精简代码

仅包含必需内容的单个 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 Admin > WCPOS > 设置 > 收银台
  2. 在列表中找到新网关并启用
注意

默认情况下，该网关在常规网页结账中处于禁用状态。WCPOS 通过自身设置控制 POS 中显示哪些网关。

手动设置​

如果不想使用脚本，也可以自行替换占位符。在文本编辑器中打开每个文件，然后查找并替换以下内容：

占位符填写内容示例
{{GATEWAY_NAME}}网关显示名称现金付款
{{GATEWAY_SLUG}}URL 安全标识符（小写字母、连字符）cash-payment
{{GATEWAY_DESCRIPTION}}网关简短说明在 WCPOS 中接受现金付款
{{GATEWAY_DEFAULT_DESCRIPTION}}结账时向收银员显示的文字在 POS 中使用现金付款
{{GITHUB_USERNAME}}您的 GitHub 用户名kilbot
{{REPO_NAME}}您的仓库名称cash-payment-gateway
{{AUTHOR_NAME}}您的姓名kilbot
{{GATEWAY_ID}}将连字符替换为下划线的 slugcash_payment
{{GATEWAY_CLASS_NAME}}每个单词首字母大写，并用下划线连接Cash_Payment
{{GATEWAY_FUNCTION_PREFIX}}与网关 ID 相同cash_payment

然后将 wcpos-{{GATEWAY_SLUG}}.php 重命名为与您的 slug 匹配的名称（例如 wcpos-cash-payment.php）。

提示

设置脚本会根据名称和 slug 自动生成 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,
    ) );
}

然后，您可以通过 process_payment() 在 $_POST['my_gateway_reference'] 中读取提交的值。请记得使用 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 Admin > 插件 中启用插件
  • 前往 WP Admin > WCPOS > 设置 > 收银台，确认网关已启用
  • 确认已安装并启用 WooCommerce
网关显示在网页结账中
  • 确保在网关构造函数中设置了 $this->enabled = 'no';
  • WCPOS 会在 POS 请求中覆盖此设置，因此该网关应仅显示在 POS 中
订单一直处于“处理中”而非“已完成”状态
  • WooCommerce 会根据商品类型设置订单状态。包含实体商品的订单会保持“处理中”状态——这是 WooCommerce 的正常行为。只有全部商品均为虚拟商品或可下载商品的订单才会自动标记为“已完成”。

要求​

WCPOS: POS 结账需要 Pro 版本
WordPress: 安装了 WooCommerce 的 WordPress
PHP: 自定义网关需要 PHP 基础知识

资源​

示例网关​

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