Square Terminal 支付网关
Square Terminal 支付网关允许您直接从 WCPOS 在 Square Terminal 硬件上收取 WooCommerce 订单付款。付款请求由 WooCommerce 发起，在已配对的 Square Terminal 设备上完成，结果会写回订单。
功能特性
硬件集成
将付款发送至已配对的 Square Terminal 设备，收取面对面刷卡付款
一键连接
直接向 Square 授权——无需创建或粘贴访问令牌
可靠的完成确认
付款通过轮询和后台清扫程序确认，Webhook 可加快这一过程
安全交易
符合 PCI 标准的持卡交易处理，在 Square 硬件上完成
沙盒与生产环境
在切换到正式支付之前，请先使用 Square 沙盒进行验证
工作原理
与基于浏览器 SDK 的支付网关不同，Square Terminal 使用 Square 的服务端 Terminal API。当您发起支付时，WooCommerce 会为该订单创建一个 Terminal Checkout，Square 将其推送到已配对的设备。顾客在终端上完成支付，结果会写回订单。
付款如何确认。 付款进行期间，POS 会轮询 Square，后台清扫程序会核对轮询遗漏的任何情况——例如浏览器标签页被关闭。Square Webhook 是可选的补充，可缩短等待时间；它们并非必需，没有 Webhook 的站点也绝不会丢失付款。
Square Terminal 设备必须在线，并登录到与插件相同的 Square 账户和位置。
安装设置
安装 Square Terminal for WooCommerce
从 WP Admin > POS > Settings > Extensions 安装，或从 GitHub 发布页面下载最新的插件 zip 文件（不是 GitHub 源代码 zip 或 tarball），然后通过 Plugins > Add New > Upload Plugin 上传。
连接到 Square
- 前往
WP Admin > WooCommerce > Settings > Payments并打开 Square Terminal - 在 Square account 下选择环境——
Sandbox用于测试，Production用于正式支付 - 点击 Connect to Square 并批准 Square 向您展示的权限
- 选择位置 ID——即 Terminal 接收付款所属的 Square 位置
请在连接之前选择环境。一次连接只覆盖一个环境；沙盒连接绝不能授权生产环境的付款。
环境和位置 ID 会从其设置中预填充。仅会读取这两个值——两个插件之间不共享任何凭据，您仍需在此处连接或提供访问令牌。
打开 Advanced settings，粘贴所选环境的访问令牌，而不进行连接。其他一切工作方式完全相同。
配对您的 Square Terminal
在 Terminal 下：
- 点击 Create Device Code——会出现一个配对代码
- 在 Square Terminal 上打开设备代码登录界面并输入该代码。如果该 Terminal 当前已登录 Square POS 或其他集成，请先退出——当它被其他应用占用时，无法进入设备代码界面。
- 点击 Check for readers 确认它现在出现在 Paired with this plugin 下
配对之前列表为空是正常现象，而不是故障。Square 的设备 API 只会报告已设置为 Terminal API 用途的 Terminal——运行 Square POS 的 Terminal 在其上输入设备代码之前根本不会出现。
在 WCPOS 中启用
- 前往
WP Admin > POS > Settings > Checkout - 找到 Square Terminal 网关并为 POS 启用它
- 保存设置
WooCommerce 设置界面上的 Enable/Disable 复选框仅控制在线商店的结账。只要此网关已配置好，无论是否勾选该复选框，WCPOS 都会自动使用它。
配对 Terminal
在收银员可以选择某台 Square Terminal 之前，它必须与此插件配对。配对会创建一个 Terminal API Device Code，而这是插件寻址该设备的唯一方式。
在设置界面的 Terminal 下：
- Create Device Code —— 生成一个要在 Terminal 上输入的代码。它有效期很短；如果过期，请重新生成一个。
- Check for readers —— 列出 Square 能看到的内容，分为两组：
- Paired with this plugin —— 可在结账时选择
- Other devices Square can see at this location —— 由其他应用设置，因此在与此插件配对之前无法在此选择
- Validate Settings —— 对照 Square 检查凭据和位置
Device Code 属于创建它的应用，因此由其他 Terminal API 集成设置的 Terminal 会出现在 Other devices Square can see 下，但无法在此处选择。运行 Square POS 的 Terminal 则根本不会出现。
无论哪种情况，解决办法都相同：让 Terminal 退出它当前配对的对象，然后在此处输入一个新的 Create Device Code。
Webhook
Webhook 是可选的。它们可以缩短付款确认所需的时间。无论如何，轮询和后台清扫程序都会确认每一笔付款，因此没有 Webhook 订阅的站点仍然可以正常工作——只是结算稍慢一些。
Webhook 订阅属于某个 Square 应用，而添加订阅需要在 Square Developer Dashboard 中拥有该应用的访问权限。如果您使用 Connect to Square 进行连接，那么您授权的是 WCPOS 应用，而不是您自己的应用，因此没有可供您添加订阅的仪表板，也没有可供您复制的签名密钥。
付款仍会正常确认——通过轮询和清扫程序。以下步骤仅适用于您在 Advanced settings 下使用自己的访问令牌设置插件的情况。
要添加 Webhook，请使用您自己的 Square 应用：
- 在设置界面的 Terminal → Webhooks 下，点击 Copy 复制 Webhook URL
- 在 Square Developer Dashboard 中打开您的应用，前往 Webhooks
- 为
terminal.checkout.updated事件添加订阅，并将该 URL 粘贴为通知 URL - 将 Square 中的 Webhook Signature Key 复制到插件的 Advanced settings 中
随后，Webhooks 行会报告是否已收到经签名验证的 Webhook，以及收到的时间。
Square 会针对它所收到的通知 URL 对每个 Webhook 进行签名。如果 Square 中的 URL 与插件中的哪怕相差一个字符，每次投递都会验证失败。请使用 Copy 按钮，而不要手动输入。
Square 的 Webhook Subscriptions API 的作用范围是应用，而不是单个卖家，并且无法使用卖家访问令牌调用。因此插件无法代您创建该订阅。
如果 Webhook 不再通过验证
当当前设置下还没有 Webhook 到达并通过验证时，Webhooks 行会显示 Not verified yet。如果已经有付款运行过，请按以下顺序检查：
- Advanced settings 中的 Webhook Signature Key 与 Square 中的一致
- Square 中的通知 URL 与插件中显示的 URL 完全一致
- 已订阅
terminal.checkout.updated事件 - 您的站点可通过 HTTPS 公开访问——请在 Square Dashboard 中检查投递尝试记录
更改环境、Webhook URL 或签名密钥会重置该行，直到下一个 Webhook 到达为止。这是有意为之：在旧设置下验证通过的投递，并不能说明新设置的情况。
设置项参考
设置界面按照安装设置的运行顺序排列。
| 部分 | 包含内容 |
|---|---|
| Square account | 环境、Connect to Square、位置 ID |
| Terminal | 配对控件、读卡器列表、Webhook 状态 |
| Checkout behaviour | 跳过收据界面、收集签名、调试日志 |
| Advanced settings | 访问令牌、Webhook 签名密钥、Webhook URL 覆盖 |
Advanced settings 默认折叠。它包含手动访问令牌（仅在您不使用连接方式时才需要）以及 Webhook 签名密钥。除非您的公开 URL 与插件推导出的 URL 不同（例如位于代理或自定义域名之后），否则 Webhook URL 覆盖应保持为空。
使用方法
处理付款
- 添加商品：在 POS 中将商品添加到购物车
- 选择网关：选择“Square Terminal”作为付款方式
- 选择设备：从 Terminal Device 列表中选择已配对的终端
- 发起付款：点击 Start Payment——Square 会将结账推送到设备
- 顾客付款：顾客在 Square Terminal 上轻触、插入或刷卡完成付款
- 完成：等待期间状态会实时更新，一旦 Square 确认付款，订单便会标记为已支付
在 Sandbox 中，设备列表包含 Square 文档中的测试设备 ID，因此无需硬件即可演练各种结果——成功、超时、离线。
付款控制
- Start Payment：向选定的终端发送新的付款请求
- Cancel Payment：取消终端上正在进行的付款
- Check Status：立即向 Square 查询当前状态
- Release Payment：断开无响应的终端，以便通过其他方式支付该订单；被放弃的结账仍会在后台完成核对
- Payment Log：可选的按订单日志，记录每个 Square 步骤和结果
订单管理
- 经过验证的完成确认：只有在付款对照 Square 的 Payment 对象验证通过后，订单才会标记为已支付——绝不会基于未经验证的信号
- 付款追踪：Square 标识符和付款日志存储在订单中，关键步骤会写入订单备注
- 小票生成：付款成功后会生成标准 POS 小票
要求
硬件兼容性
Square Terminal 使用 Square 的服务端 Terminal API：结账由您的站点创建，并由 Square 传送到已配对的设备。终端必须在线，并登录到与插件相同的 Square 账户和位置。
支持的终端
- Square Terminal ✅ — Square 专用台面刷卡终端
范围与限制
- 专注于 POS / 订单支付 流程。在面向客户的店面结账页面上默认关闭，需要显式启用。
- 仅支持收款——暂不支持退款。Square 标识符已存储在订单中，以便后续添加退款支持。
- Webhook 订阅必须在 Square 中手动添加；参见 Webhook。
故障排除
常见问题
Terminal Device 列表为空
- 终端必须先与此插件配对——请使用 Create Device Code 并在设备上输入该代码
- 通过 Square Dashboard 或 Square POS 应用配对的终端在此处配对之前不会出现
- 点击 Check for readers：如果它出现在 Other devices Square can see 下，说明它存在但未与此插件配对
- 确认位置 ID 与终端所登录的位置一致
设备无法配对
- 确保在设备代码过期之前已输入该代码——请用 Create Device Code 重新生成一个
- 确认终端已联网，并且登录的 Square 账户和位置 ID 与插件一致
- 检查环境是否与终端所登录的账户匹配
Validate Settings 失败
- 如果已连接，请检查 Square account 行是否仍显示 Connected to Square；如果提示您重新连接，说明授权已失效
- 如果使用访问令牌，请确认它与所选环境匹配——沙盒令牌无法在生产环境中使用，反之亦然
- 确认位置 ID 属于该账户
终端上付款已完成，但订单更新缓慢
- 这正是 Webhook 所解决的问题。没有 Webhook 时，订单会在轮询或后台清扫程序下一次核对时更新
- 检查 Webhooks 行——如果在付款运行之后它仍显示 Not verified yet，请按照如果 Webhook 不再通过验证处理
- 订单绝不会丢失：清扫程序会核对轮询遗漏的任何付款
无法发起付款
- 确认已选择终端，且设备已配对并处于在线状态
- 检查设备是否已登录到已配置的位置 ID
- 查看付款日志以及
WooCommerce > Status > Logs中的 Square API 消息
提示需要重新连接到 Square
Square 授权会自动续期。如果续期无法完成，插件会结束该授权，而不是让它停留在不可用的状态，设置界面则会要求您重新连接。点击 Reconnect to Square——无需更改其他任何内容。
获取帮助
如需技术支持：
- 访问 GitHub 仓库报告问题
- 查阅 Square Terminal API 文档，获取硬件和 API 指南
- 如有账户和硬件问题，请联系 Square 支持团队
日志写入 WooCommerce > Status > Logs 中的 sqtwc 句柄下，并记录每次设备查询和 Webhook 结果。
截图
截图将在后续更新中添加，届时将展示：
- Square account、Terminal 和 Advanced settings 各部分
- 在 WCPOS 设置中启用网关
- POS 结账中的支付处理流程