Windcave 终端支付网关
Windcave 终端支付网关可让您通过 Windcave HIT 使用 Windcave 终端收取现场银行卡付款。付款从 WCPOS 发起，并在终端上完成，确认信息会写入 WooCommerce 订单。
0.1.0 是首个版本。Windcave 要求集成通过 QA 认证后才能用于生产环境，而此集成尚未获得认证。在认证完成前，请使用 Windcave UAT（测试）凭据。Vendor ID 由 Windcave 在认证期间发放。
功能
云端 HIT 连接
通过 Windcave 的云端 HIT 服务连接，每台终端配置一个 Station ID，无需本地配对
在屏幕上显示终端提示
在付款面板中查看终端提示和按钮，包括用于签名验证的 YES/NO 和 CANCEL
验证后完成
只有在检查付款参考号、金额、环境、订单总额和货币后，订单才会完成
暂放付款
超时后，可暂放待处理的付款并继续操作，同时由后台检查跟进
结果通知
启用可选的结果通知（FPRN），让 Windcave 通知您的站点，作为轮询的备用方式
工作原理
此支付网关通过 HTTPS 使用 Windcave HIT（主机发起交易）。Environment 用于选择 UAT 或生产端点，每台终端通过 Windcave 发放的 Station ID 标识。
发起付款时，会将完整订单总额和货币发送到终端。付款页面每隔 1.5 秒向 Windcave 轮询一次，并显示终端提示和可用按钮。可选的 Result notifications (FPRN) 可让 Windcave 通知站点，作为轮询的备用方式。
设置
安装 Windcave Terminal for WooCommerce
从 GitHub 发布页面 下载插件 zip 资源（而不是 GitHub 源代码 zip），通过 插件 > 新增 > 上传插件 上传，并在安装且启用了 WooCommerce 后激活。
激活需要 PHP 7.4+ 和 PHP DOM 扩展（php-xml）。缺少其中任意一项时，系统会显示消息并拒绝激活。
从 Windcave 获取 HIT 凭据
向 Windcave 申请 HIT username、HIT key，以及每台终端各自的 Station ID。通过 Windcave 的 集成要求表单 申请开发账户。
UAT 和生产凭据彼此独立。此集成尚待认证，请使用 UAT 凭据。
配置支付网关
- 前往
WP Admin > WooCommerce > 设置 > 支付，然后打开 Windcave Terminal - 将 Environment 设为
UAT (testing)（默认值）。Windcave 完成认证并提供生产凭据后，才能使用Production - 输入 Windcave 发放的 HIT username 和 HIT key
- 输入您的 Station IDs，每行一个
- (可选) 设置 Default Station ID。启用 Lock terminal selection 后，将始终使用此默认项，并禁止收银员更改
- 在 Windcave 于认证期间发放 Vendor ID 前，请留空
- 保存设置
启用结果通知（可选）
启用 Result notifications (FPRN) 并保存，以便在交易结果就绪时让 Windcave 通知您的站点。这是轮询的备用方式。
在 WCPOS 中启用
- 前往
WP Admin > POS > 设置 > 结账 - 找到 Windcave Terminal 支付网关，并为 POS 启用它
- 保存设置
WooCommerce 设置页面上的 Enable/Disable 复选框仅控制在线商店结账。无论是否勾选该项，WCPOS 都会在配置完成后使用此支付网关。
设置参考
| 设置 | 功能说明 |
|---|---|
| Enable/Disable | 启用在线商店结账的支付网关。POS 是否启用由 POS > 设置 > 结账 控制 |
| Title | 结账时显示的标签；默认值为 Windcave Terminal |
| Description | 结账说明；默认值为 Pay in person on the Windcave terminal. |
| Environment | UAT (testing)（默认值）或 Production。两种环境使用不同的 HIT 凭据；生产环境需要 Windcave 认证 |
| HIT username | Windcave 针对所选环境发放的 HIT 用户名 |
| HIT key | Windcave 针对所选环境发放的 HIT 密钥 |
| Station IDs | 每行填写一个 Windcave 发放的 Station ID，每台终端对应一个 |
| Default Station ID | 预先选定的 Station；未选择 Station 时也会使用此项 |
| Lock terminal selection | 始终使用默认 Station，收银员无法更改。仅在设置了默认项时生效 |
| Vendor ID | 由 Windcave 在认证期间发放。在 Windcave 提供之前请留空 |
| POS name | 发送给 Windcave、用于标识 POS 的名称；默认值为 WCPOS |
| Result notifications (FPRN) | 请求 Windcave 在交易结果就绪时通知站点，作为轮询的备用方式。默认关闭 |
| Checkout logs | 在付款面板中显示日志工具。默认关闭 |
| Log level | Off、Errors only 或 Debug。默认值为 Debug；记录请求和响应时会遮蔽密钥及银行卡数据 |
| Support | 提供 Download support bundle，以及用于查看日志的链接 WooCommerce > Status > 日志 |
没有连接测试按钮：首次发起付款时会检查凭据和 Station IDs。
使用方法
处理付款
- 添加商品：在 POS 中将商品添加到购物车
- 选择网关：选择 Windcave Terminal 作为付款方式
- 选择终端：选择一个 Station，或使用已锁定的默认项。当有两个或更多 Station 且未设置默认项时，必须进行选择
- 发起付款：点击 Start Terminal Payment，将订单总额发送到终端
- 按照提示操作：屏幕上会显示终端提示和可用按钮，包括用于签名验证的 YES/NO，以及终端提供时的 CANCEL
- 自动完成：付款获批并通过验证后，订单即完成，POS 会转到收据页面
付款控制
- Start Terminal Payment：向所选 Station 发送新的付款请求
- Cancel Terminal Payment：在终端提供 CANCEL 按钮时按下该按钮。否则，请在终端上取消，或在出现相应选项时暂放付款
- Set payment aside：在 5 分钟超时后显示。付款尝试将交由 10 分钟后台检查跟进，期间您可以通过其他方式收款；这不会取消 Windcave 上的付款
- 重新加载页面：恢复已在进行中的付款
收据
Windcave 返回的终端收据文本会作为 WooCommerce 中的私密订单备注保存。
退款
0.1.0 不支持通过 WooCommerce 退款。请在 Windcave 门户（Payline）或终端上退款，然后在 WooCommerce 中手动记录退款。
日志和支持包
在 WooCommerce > Status > 日志 中查找日志，来源为 windcave-terminal。日志级别默认为 Debug，记录 Windcave 请求和响应时会遮蔽密钥及银行卡数据。
点击支付网关设置页面上的 Download support bundle，下载 .json 文件，并连同订单号一起发送。文件包含环境详情、已遮蔽 HIT 密钥和用户名的设置、最近 20 个订单的付款尝试（已移除收据），以及最新两个日志文件末尾的 1,000 行；日志行可能包含已遮蔽银行卡号的终端收据文本。
如果 WooCommerce 使用数据库日志处理程序，支持包将不包含日志行。请改为从 WooCommerce > Status > 日志 导出日志。
启用 Checkout logs，以在付款面板中显示日志工具。
要求
适用范围与限制
此集成尚未获得 Windcave 认证。在 Windcave QA 认证完成前，请使用 UAT 凭据；认证前请勿在生产环境中使用。
- 0.1.0 不支持通过 WooCommerce 退款
- 不支持小费、附加费和取现
- 仅支持保留两位小数的货币
- 终端会收取完整订单总额；不支持在终端上仅支付部分订单金额
- 必须手动输入 Station IDs；不会自动发现终端
- 此支付网关专为 POS 设计。在在线商店中，仅适用于订单付款页面
故障排除
常见问题
激活被拒绝：需要 PHP DOM 扩展（php-xml）
- 服务器缺少 PHP DOM 扩展
- 请联系主机服务商启用 php-xml。激活还需要 PHP 7.4+
未配置 Station IDs
- Station IDs 设置为空
- 在支付网关设置中添加 Windcave 发放的 Station ID，每行一个，然后保存
尚未配置 Windcave HIT 凭据
- HIT username 或 HIT key 为空
- 在支付网关设置中填写两项并保存。确保 Environment 与这些凭据相匹配
终端仍在完成先前的交易
- 该 Station 上仍有先前的交易正在进行
- 在终端上完成或取消该交易，然后重试
Windcave 中没有此交易的记录
- 初始 30 秒宽限期过后，Windcave 仍没有记录
- 重新发起付款
Windcave 已批准付款，但无法将其应用到订单
- 已批准的结果未通过完成此订单所需的检查
- 请检查 Windcave 门户 和 订单备注，然后再扣款
此付款是在另一个环境中发起的
- 付款进行期间，Environment 已更改
- 切换回发起付款时使用的环境，或检查 Windcave 门户
获取帮助
- 从支付网关设置页面发送支持包，并附上订单号
- 访问 GitHub 仓库 报告问题
- 有关账户、凭据和硬件的问题，请联系 Windcave 支持