VibeFox Square for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更旧的 PHP 版本上安装。
货币：购物车货币必须与您的 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. 在后台进入 Modules > Module Manager，点击 Upload a module，选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Square Gateway 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（见许可证密钥）。
4. 保持 Sandbox Mode 开启，并输入 Sandbox 的 Application ID、Access Token 和 Location ID（见配置）。点击 Save：模块会与 Square 核对凭据。
5. 开启 Enable/Disable，保存，并使用 Square 沙盒测试指南中的测试卡进行一次付款测试。然后关闭 Sandbox Mode，输入生产环境凭据并再次保存。
安装时，模块会创建订单状态 Square payment on hold。PrestaShop 会为新的付款模块分配安装时启用的货币、国家和客户群组。请检查这些设置，并在 Payment > Preferences 中勾选之后添加的国家。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Square Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。Sandbox 模式开启时，字段上方会显示 Square Gateway 当前处于 SANDBOX 模式，不会产生真实扣款。 若 Square 已启用，但所选模式的 Application ID、Access Token 或 Location ID 缺失（此时付款方式会在结账页面隐藏），或 Square 无法处理您商店的默认货币，或您的 Square 位置货币与之不同，页面都会发出警告。
保存时，模块会与 Square 核对所选模式的凭据。无论如何，设置都会被保存。如果 Square 拒绝 Access Token、该令牌找不到 Location ID、无法核对凭据，或位置货币与商店货币不同，您会看到警告。Square 只能以位置货币扣款：模块会记住已核对位置的货币，并对其他货币的购物车隐藏付款方式。如果在实时模式中使用了 sandbox Application ID，或反之，模块也会发出警告。
Square
Enable/Disable：Enable Square Payment Gateway 用于开启或关闭该付款方式。默认：off。
Title：顾客在结账时看到的付款方式标题。它也是订单中保存的付款方式名称。默认：Credit / debit card。必填。
Description：顾客在结账时看到的付款方式描述。默认：Pay securely with your credit or debit card via Square。在沙盒模式下会添加 (SANDBOX MODE)。
Square 账户
打开 Square Developer Dashboard（本节包含链接），选择您的应用，从 Credentials 页面复制 Application ID 和 Access token（Sandbox 与 Production 的值是分开的），并从 Locations 页面复制 Location ID。位置货币必须与您的商店货币一致。页面只显示所选模式的凭据字段：Sandbox Mode 开启时显示 sandbox 字段，关闭时显示 live 字段。两套字段都会保留保存的值。
Sandbox 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。
已保存的访问令牌不会再次显示。该字段保持为空，并显示 已保存 — 留空即可保留。 只有在需要更改时才输入新值。
Clear saved secrets：勾选访问令牌并点击 Save 即可删除。空字段会保留已保存的值。
高级
Debug log：错误和警告始终会被记录。开启后，还会将每个请求和响应（不含银行卡数据或密钥）记录到模块文件夹中的 logs/wc_sqg_debug.log.php。该文件无法通过网页打开。默认：off。
Log：显示日志的大小和最新条目。点击 Clear log 即可清空。
Delete data on uninstall：开启时，卸载模块会删除网关设置和日志文件。订单中的 Square 付款和退款，以及 Square payment on hold 订单状态始终会保留。默认：off。
结账页面
在付款步骤中，顾客选择付款方式（默认为 Credit / debit card），并在描述下方显示的 Square 银行卡表单中输入卡信息。顾客下单时，银行卡会在浏览器中通过买家验证（3-D Secure / SCA）进行令牌化：购物车总额、货币和账单地址会传递给 Square，顾客的银行可能会要求确认。您的商店只会收到一次性令牌。
随后，模块会通过 Square Payments API 以购物车货币扣除购物车总额，并将购物车 ID 作为参考，附带一条含购物车编号和商店名称的 Cart # 备注，以及顾客的电子邮件地址。付款会立即被捕获。只有在 Square 确认后，订单才会被标记为已付款：Square 的响应必须显示一笔 COMPLETED 付款，且金额、货币、购物车 ID 和位置与之完全一致。随后订单以 Payment accepted 创建，顾客会看到标准订单确认页面，显示 您的银行卡付款已收到。 以及 Square 收据的链接。如果付款不是 COMPLETED，或任一值不一致，订单将以 Square payment on hold 创建，页面会显示 您的银行卡付款已收到，正在审核中。审核完成后，我们会尽快更新您的订单。
每个购物车同一时间只执行一次付款尝试。如果顾客点击两次，或在两个标签页中付款，第二次尝试会看到 此订单正在付款中。请稍候，并在再次尝试前检查您的电子邮件。 请求具有幂等性：相同的购物车、银行卡令牌和金额绝不会产生第二笔付款，已有订单的购物车也绝不会被再次扣款。
如果 Square 没有响应（网络问题、超时、服务器错误），请求会使用相同的幂等密钥重试一次。如果仍然没有响应，模块会立即在 Square 中查找此购物车的付款。如果找到，则用它创建订单。如果找不到任何付款，顾客会停留在结账页面，并看到 无法从付款服务商获得确认。请稍等一分钟后重试——如果您的银行卡已被扣款，系统会识别该付款，您不会被重复扣款。 下一次尝试会先重新查找之前的付款。如果连查询时也无法联系 Square，订单会在没有付款的情况下以 Square payment on hold 创建，并附带银行卡可能已被扣款的备注，确认页面会显示 无法从 Square 获得您银行卡付款的确认。再次付款前，请检查您的电子邮件和银行卡对账单，或与我们联系。
当银行拒绝银行卡时，不会创建订单，顾客会停留在结账页面，并根据 Square 的错误代码看到简短提示，例如 您的银行卡被拒绝。请使用其他银行卡或付款方式。、银行卡安全码（CVV）不正确。请检查后重试。 或 您的银行要求额外验证（3-D Secure）。请重新输入银行卡并完成验证。 购物车会被保留，顾客可以使用其他银行卡再试一次。技术原因会记录到日志中。
模块仅接受即时捕获的银行卡付款。不支持保存的银行卡或客户资料、订阅、Apple Pay、Google Pay、Cash App Pay、Afterpay、ACH 或 Square 礼品卡，不支持仅授权付款、Square Webhook，也不与 Square 同步商品或库存。争议请在 Square Dashboard 中处理。
订单与退款
订单状态
No order yet：银行卡被拒绝，或 Square 的响应丢失且未找到付款。仅存在购物车。
Payment accepted：Square 确认了一笔与购物车总额相符的 COMPLETED 付款。付款会以 Square 付款 ID 作为交易 ID 记录，备注中显示付款 ID、银行卡品牌及后 4 位数字，以及模式（sandbox 或 live）。
Square payment on hold：Square 返回的付款不是 COMPLETED（例如 APPROVED），或金额、货币、参考或位置不同。备注 Square 付款需要审核 会显示付款 ID、状态和金额。COMPLETED 付款会以 Square 实际扣款的金额记录在订单上。此状态还用于付款期间购物车发生变化的情况，以及 Square 的响应丢失且无法核实的情况（此时不记录任何付款）。发货前请在 Square Dashboard 中核实付款。
Refunded：付款已通过模块全额退款。
如果已有订单的购物车又收到第二笔付款，订单不会被修改。备注会提醒您核实该付款，并在 Square Dashboard 中退还重复付款。
Square 区块
订单页面会显示 Square 区块，包括 Square 付款 ID（链接到 Square Dashboard 中的付款）、Square 状态、银行卡品牌及后 4 位数字、Paid / order / refunded 金额、环境和位置、Square 收据链接、沙盒付款的 Sandbox 标记、退款记录以及订单的 Square notes。银行卡号码绝不会被存储。
退款
在 Square 区块中输入金额（会自动填入尚未退款的金额），可选填原因，然后点击 Refund via Square。确认提示 通过 Square 退还此金额？此操作无法撤销。 支持全额和部分退款。您需要具有编辑订单的权限。退款会以 Square 实际扣款的金额和货币进行，因此在金额不一致的情况下，您可以退还至顾客实际支付的金额，而不是订单总额。退款会发送到付款所在的环境（sandbox 或生产）和位置，因此必须设置该模式的 Access Token。退款请求具有幂等性，若 Square 未响应，会重试一次。Square 接受的退款（状态 PENDING 或 COMPLETED）会连同 Square 退款 ID 一起添加到退款记录和备注中。若 Square 拒绝，区块会显示错误，且不会记录退款。全额退款会将订单设为 Refunded。部分退款不会更改状态。
模块不会创建退款凭证。订单页面上 PrestaShop 的标准退款按钮不会通过 Square 退还款项。Square 在其自身端完成退款：Square 之后拒绝的退款不会回报，在 Square Dashboard 中所做的退款也不会显示在 PrestaShop 中。
许可证密钥
模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Square Gateway 许可证区块位于 Modules > Module Manager > VibeFox Square Gateway > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏方式显示密钥，并显示状态（例如许可证有效的截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店中移除密钥）。它们下方有一行 Product: presta-payment-square 和链接 Manage licenses and domains in your account，点击后会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。区块中的文字会跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。更改商店地址后，或在账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后一次已知的状态。
一个密钥只能用于一个域名：即主商店的域名，多店铺设置中也是如此。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账页面不会向顾客显示 Square。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账页面进行测试。提醒会出现在 Modules > Module Manager 的 Alerts 标签中。现有订单不受影响：已付款的订单保持已付款状态，退款功能仍可使用。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台时，状态会自动重新检查：密钥输入后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
Square 未在结账页面显示：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的 Application ID、Access Token 和 Location ID 是否已填写。检查购物车货币是否为 USD、CAD、AUD、JPY、GBP 或 EUR，并与您的 Square 位置货币一致。设置页面会针对上述每个问题显示警告。在 Payment > Preferences 中，检查模块是否允许用于购物车货币、顾客所在国家和顾客所属群组。
银行卡表单无法加载：顾客会看到 无法加载银行卡表单。请刷新页面或选择其他付款方式。 请检查 Application ID 和 Location ID 是否属于所选模式（sandbox ID 以 sandbox- 开头）。如果顾客点击得太早，会显示 银行卡表单仍在加载中。请稍候片刻后重试。
保存后付款方式消失：Square 位置的货币与购物车货币不同。请输入一个与您商店货币相同的 Square 位置的 Location ID 并再次保存：校验成功后，付款方式会重新显示。
Square 拒绝了所选模式的 Access Token：该令牌属于另一模式，或不正确。请从应用的 Credentials 页面重新复制，并检查 Sandbox Mode。
未找到该 Access Token 对应的 Location ID：请从同一应用和同一模式的 Locations 页面复制 Location ID。
顾客看到了 无法从付款服务商获得确认：Square 没有响应，且尚未找到付款。请在 Square Dashboard 中检查该位置的付款（参考 = 购物车 ID）。如果顾客再次尝试，模块会先查找之前的付款，并使用它创建订单，而不是再次扣款。
顾客看到了 您的付款已收到，但订单无法自动完成：银行卡已被扣款，但 PrestaShop 无法创建订单（例如，当时模块已被禁用）。请查看日志，然后手动创建订单，或在 Square Dashboard 中退款。
订单处于 Square payment on hold：请阅读 Square 区块中的备注（参见订单状态）。在 Square Dashboard 中核实付款，然后发货或退款。
退款因模式相关的消息失败：付款是在 sandbox 或 live 模式下进行的，而该模式的 Access Token 未设置。请输入后重试。
其他错误：开启 Debug log，并查看模块页面上的 Log 字段。
卸载
进入 Modules > Module Manager，打开 VibeFox Square Gateway 旁边的菜单，选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 开启，网关设置和日志文件会被删除。如果关闭，所有设置都会保留，供以后重新安装时使用。订单中的 Square 付款和退款，以及 Square payment on hold 订单状态始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注、Square 付款 ID 和交易 ID。
Square 是其各自所有者的商标。本模块与 Square 无关联，也未获得 Square 的认可。