VibeFox Square for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。没有 WooCommerce，插件无法激活。
PHP：8.0 或更高版本。
商店货币：您的 Square 位置所用货币：USD、CAD、AUD、JPY、GBP 或 EUR。对于其他货币，结账时会隐藏该付款方式。Square 支持美国、加拿大、澳大利亚、日本、英国、爱尔兰、法国和西班牙的卖家。
Square 账户：您需要在 Square Developer Dashboard 中创建一个应用。从中复制 Application ID 和 Access Token（Credentials 页面）以及 Location ID（Locations 页面）。Sandbox 和 Production 的值是分开的。无需 Webhook：插件直接从 Square 的响应中获取付款结果。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_square_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Square > Manage，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 保持 Sandbox Mode 开启，并输入 sandbox 的 Application ID、Access Token 和 Location ID（参见「配置」）。保存：插件会与 Square 核对凭据。
6. 开启 Enable/Disable，并使用 Square sandbox 测试指南中的测试卡测试一笔付款。然后取消勾选 Sandbox Mode，输入正式环境的凭据并再次保存。
配置
所有设置都在同一个页面：WooCommerce > Settings > Payments > Square。在 Sandbox 模式开启时，页面在字段上方显示 Square Gateway 当前处于 SANDBOX 模式。不会产生任何真实扣款。。如果已启用 Square 但所选模式的 Application ID、Access Token 或 Location ID 缺失（此时结账页面会隐藏该付款方式），或者 Square 无法处理商店货币，页面也会提示您。在付款方式列表中，Sandbox 模式开启时，Square 会显示 Test mode 标记。
保存时，插件会与 Square 核对所选模式的凭据。如果 Square 拒绝 Access Token、该令牌找不到 Location ID、无法核对凭据，或位置货币与商店货币不一致，您会看到错误提示。Square 只能以位置货币进行扣款：插件会记住已核对位置的货币，并在结账页面对任何其他货币隐藏该付款方式，设置页面也会持续显示警告。如果在正式模式中使用了 sandbox 的 Application ID，或反之，插件也会发出警告。
General
Enable/Disable：Enable Square Payment Gateway 用于启用或禁用该付款方式。默认：off。
Title：顾客在结账时看到的付款方式标题。默认：Credit / debit card。
Description：顾客在结账时看到的付款方式说明。默认：Pay securely with your credit or debit card via Square。
Square account
打开 Square Developer Dashboard，选择您的应用，从 Credentials 页面复制 Application ID 和 Access token（Sandbox 和 Production 的值是分开的），并从 Locations 页面复制 Location ID。位置货币必须与您的商店货币一致。页面只显示所选模式的凭据字段：Sandbox Mode 开启时显示 sandbox 字段，关闭时显示正式环境字段。
Sandbox Mode：Enable sandbox (test) mode。付款会发送到 Square sandbox，不会收取真实费用。请使用 Square 测试卡。默认：on。
Sandbox Application ID：您的 Square sandbox Application ID（以 sandbox-sq0idb- 开头）。
Sandbox Access Token：您的 Square sandbox Access Token。
Sandbox Location ID：您的 Square sandbox Location ID。
Live Application ID：您的 Square 正式环境 Application ID（以 sq0idp- 开头）。
Live Access Token：您的 Square 正式环境 Access Token。
Live Location ID：您的 Square 正式环境 Location ID。
Advanced
Debug log：Log API requests and responses。错误始终会被记录。开启后还会记录每个请求，但不包含银行卡数据或密钥。日志位于 WooCommerce > Status > Logs，来源为 wcp_square_gateway。默认：off。
Delete data on uninstall：Remove all plugin data when the plugin is deleted。删除插件时，会删除网关设置和日志文件。订单付款数据会保留。默认：off。
结账
顾客选择付款方式（默认为 Credit / debit card），并在描述下方显示的 Square 银行卡表单中输入卡信息。在 sandbox 模式下，结账页面会显示 sandbox 提示。顾客点击 Place order 后，银行卡会在浏览器中进行令牌化，并进行买家验证（3-D Secure / SCA）：金额、货币和账单联系人会传递给 Square，顾客的银行可能会要求确认。您的服务器只会收到一次性令牌。
随后，插件会通过 Square Payments API，以订单货币对订单总额使用该令牌进行扣款，并附带订单 ID 作为参考、一条包含订单号和您网站名称的 Order # 备注，以及账单电子邮件。付款会立即被捕获。只有在 Square 确认后，订单才会被标记为已付款：Square 的响应必须显示一笔 COMPLETED 付款，且金额、货币、订单 ID 和位置与订单完全一致。之后，顾客会进入订单接收页面。如果付款不是 COMPLETED 或任何数值不一致，订单会进入「暂停」状态并附带备注，顾客仍会进入订单接收页面。
每个订单同一时间只会执行一次付款尝试。如果顾客点击两次或在两个标签页中付款，第二次尝试会显示 This order is already being paid. Please wait a moment and check your e-mail before trying again.（该订单正在付款中，请稍候片刻并查看您的电子邮件后再重试。）请求具有幂等性：相同的订单、令牌和金额绝不会产生第二笔付款。
如果 Square 没有响应（网络问题、超时、服务器错误），请求会使用相同的幂等性密钥重试一次。如果仍无响应，顾客会看到 We could not get a confirmation from the payment provider. Please wait a minute and try again — if your card was already charged, the payment will be recognised and you will not be charged twice.（无法从付款服务商获得确认。请稍候一分钟后重试；如果您的银行卡已被扣款，系统会识别该付款，您不会被重复扣款。）订单备注会提示您检查 Square Dashboard。下次尝试时，插件会先在 Square 中查找该订单之前的付款，并用该付款完成订单，而不是再次扣除银行卡。
当银行拒绝银行卡时，顾客会根据 Square 的错误代码看到简短提示，例如 Your card was declined. Please use another card or payment method.、The card security code (CVV) is incorrect. Please check it and try again. 或 Your bank requires additional verification (3-D Secure). Please enter your card again and complete the verification.。技术原因会记录在订单备注和日志中。顾客可以换一张卡重试，也可以稍后在 Pay for order 页面重试。
该付款方式适用于经典结账页面、结账区块和 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅接受即时捕获的银行卡付款。不支持保存的银行卡或客户资料、WooCommerce Subscriptions 或预购、Apple Pay、Google Pay、Cash App Pay、Afterpay、ACH 或 Square 礼品卡、仅授权付款、Square Webhook，也不支持与 Square 同步商品或库存。争议（拒付）在 Square Dashboard 中处理。
订单与退款
订单状态
Pending payment：订单已创建但尚未付款，例如银行卡被拒或 Square 的响应丢失之后。
Processing：Square 已确认订单总额的 COMPLETED 付款。这是付款后 WooCommerce 的标准状态（仅包含虚拟可下载商品的订单会变为已完成）。订单备注会显示 Square 付款 ID、银行卡品牌及后 4 位数字，以及模式（sandbox 或正式环境）。交易 ID 即为 Square 付款 ID，在订单页面中会链接到 Square Dashboard 中的付款记录。
On hold：Square 返回的付款并非 COMPLETED，或其金额、货币、参考或位置不一致。备注 Square payment needs review 会显示付款 ID、状态和金额。在发货前，请在 Square Dashboard 中核实扣款、金额和货币。
插件会在订单中保存 Square 付款 ID、银行卡品牌及后 4 位数字、环境和位置。银行卡号永远不会被保存。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Credit / debit card（按钮会显示您的 Title）。支持全额和部分退款。退款会发送到付款时所在的环境（sandbox 或正式环境）和位置，因此必须已设置该模式的 Access Token。退款请求具有幂等性，如果 Square 没有响应，会重试一次。Square 接受的退款（状态为 PENDING 或 COMPLETED）会连同 Square 退款 ID 一起添加到订单备注中。如果 Square 拒绝退款，WooCommerce 会显示错误，且不会记录任何退款。
Square 在其一侧完成退款。Square 之后拒绝的退款不会回报给 WooCommerce，在 Square Dashboard 中执行的退款也不会显示在 WooCommerce 中。
许可证密钥
插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Square 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证的有效截止日期以及您的域名。使用 Check now 可重新检查状态，Change key 用于输入另一个密钥，Remove key 用于将密钥从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效的密钥，Square 不会在结账时显示给顾客。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one.（该付款方式不可用，请选择其他方式。）已登录的商店管理员仍会看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已付款的订单保持已付款状态，退款功能正常。
许可证过期后，插件仍可继续工作，但更新和支持需要续期。系统会在后台自动重新检查状态。
故障排除
结账时不显示 Square：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式的 Application ID、Access Token 和 Location ID 是否已填写。检查商店货币（或 Pay for order 页面上的订单货币）是否为 USD、CAD、AUD、JPY、GBP 或 EUR，并且与您的 Square 位置货币一致。设置页面会针对上述每个问题显示警告。
银行卡表单无法加载：顾客会看到 The card form could not be loaded. Please reload the page or choose another payment method.（无法加载银行卡表单。请重新加载页面或选择其他付款方式。）请检查 Application ID 和 Location ID 是否属于所选模式（sandbox 的 ID 以 sandbox- 开头）。如果顾客点击过早，会显示 The card form is still loading. Please wait a moment and try again.（银行卡表单仍在加载中，请稍候片刻后重试。）
银行卡正常却被拒付：位置货币必须与商店货币一致。保存设置以查看凭据核对结果；核对成功后，该付款方式会对其他货币隐藏。
Square 拒绝了所选模式的 Access Token：该令牌属于另一模式，或令牌有误。请从您应用的 Credentials 页面重新复制，并检查 Sandbox Mode。
未找到此 Access Token 对应的 Location ID：请从同一应用及同一模式的 Locations 页面复制 Location ID。
顾客看到「We could not get a confirmation from the payment provider」：Square 没有响应。请阅读订单备注，并在 Square Dashboard 中检查该位置的付款（参考 = 订单 ID）。如果顾客再次尝试，插件会先查找之前的付款，并用它完成订单，而不会再次扣款。
订单处于 On hold 状态：请阅读备注 Square payment needs review。付款不是 COMPLETED，或其金额、货币或位置与订单不一致。请在 Square Dashboard 中检查，然后处理订单或退还付款。
退款因模式相关的消息而失败：付款是在 sandbox 或正式模式下完成的，而该模式的 Access Token 未设置。请填写后重试。
其他错误：开启 Debug log，并查看 WooCommerce > Status > Logs，来源为 wcp_square_gateway。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态运行。
卸载
停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。只有开启了 Delete data on uninstall，才会删除网关设置和日志文件；否则它们会保留，供以后重新安装时使用。现有订单会保留付款备注、Square 付款 ID 和交易 ID。
Square 是其各自所有者的商标。本插件与 Square 无关联，也未获得 Square 的认可。