# 网关模板

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

## 功能[​](#features "直接链接到 功能")

#### 最少代码

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

#### 仅限 POS

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

#### 自动化设置

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

#### GitHub 发布

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

## 开始使用[​](#getting-started "直接链接到 开始使用")

1

#### 克隆模板库

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

cd woocommerce-gateway-template
```

或者点击 [GitHub 仓库](https://github.com/wcpos/woocommerce-gateway-template) 上的 **使用此模板** 按钮来创建您自己的副本。

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 中显示，通过其自己的设置进行管理。

## 手动设置[​](#manual-setup "直接链接到 手动设置")

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

| 占位符                            | 输入的内容                       | 示例                    |
| --------------------------------- | -------------------------------- | ----------------------- |
| `{{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`，因此在手动设置时您只需考虑这些信息。

## 工作原理[​](#how-it-works "直接链接到 工作原理")

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

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

## 自定义您的网关[​](#customising-your-gateway "直接链接到 自定义您的网关")

### 添加支付字段[​](#adding-payment-fields "直接链接到 添加支付字段")

如果您的网关需要收银员输入（例如，参考编号），可以覆盖 `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()` 清理任何输入。

### 更改支付行为[​](#changing-payment-behaviour "直接链接到 更改支付行为")

默认模板会立即将订单标记为已支付。如果您的工作流程要求稍后支付（如发票），则可以将 `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 ),

    );

}
```

## 修改和更新[​](#making-changes-and-updating "直接链接到 修改和更新")

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

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

提示

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

### 使用 GitHub 进行自动发布[​](#automated-releases-with-github "直接链接到 使用 GitHub 进行自动发布")

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

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

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

## 故障排除[​](#troubleshooting "直接链接到 故障排除")

网关未在 POS 显示

* 检查插件是否在 **WP 管理 > 插件** 中激活
* 转到 **WP 管理 > WCPOS > 设置 > 结账**，确保网关已启用
* 确保已安装并激活 WooCommerce

网关在网页结账中显示

* 确保在网关构造函数中设置了 `$this->enabled = 'no';`
* WCPOS 会覆盖此设置以适用于 POS 请求，因此网关应仅在 POS 中出现

订单保持在'处理中'而不是'完成'

* WooCommerce 根据产品类型设置订单状态。包含实物产品的订单保持在 "处理中" — 这是 WooCommerce 的正常行为。只有包含完全虚拟或可下载产品的订单才会自动标记为 "完成"。

## 资源[​](#resources "直接链接到 资源")

* **GitHub**: [woocommerce-gateway-template](https://github.com/wcpos/woocommerce-gateway-template)
* **WooCommerce 支付网关 API**: [WC\_Payment\_Gateway 文档](https://woocommerce.github.io/code-reference/classes/WC-Payment-Gateway.html)

### 示例网关[​](#example-gateways "直接链接到 示例网关")

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

* **[电子邮件发票](/zh-CN/payment/gateways/email-invoice.md)** — 发送发票电子邮件，以便客户稍后付款
* **[网页结账](/zh-CN/payment/gateways/web-checkout.md)** — 重定向到网页商店进行付款