VibeFox Square for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
货币：订单货币必须与您的 Square 地点的货币一致：USD、CAD、AUD、JPY、GBP 或 EUR。对于其他货币，结账时会隐藏该付款方式。JPY 按整数日元扣款。
Square 账户：您需要在 Square Developer Dashboard 中创建一个应用。从中复制 Application ID 和 Access Token（Credentials 页面），以及 Location ID（Locations 页面）。Sandbox 和 Production 的值是分开的。无需 Webhook：扩展直接从 Square 的响应中获取付款结果。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_square_gateway-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_square_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_square_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Square Gateway，点击 Install（绿色 + 按钮）。您的后台用户需要有修改支付扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。
4. 保持 Sandbox Mode 开启，并填写 Sandbox 的 Application ID、Access Token 和 Location ID（参见配置）。点击 Save：扩展会与 Square 核对凭据。
5. 开启 Enable/Disable，保存后使用 Square 沙盒测试指南中的测试卡完成一笔付款测试。然后关闭 Sandbox Mode，填写正式环境（Production）凭据，并再次保存。
OpenCart 4
1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_square_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Square Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 请按照 OpenCart 3 步骤 3 至 5 输入许可证密钥和 Square 凭据。两个版本的设置页面及其字段完全相同。
新安装时，付款方式默认关闭，沙盒模式默认开启。
配置
所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Square Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在沙盒模式开启时，设置上方会显示 Square Gateway 当前处于 SANDBOX 模式。不会产生真实扣款。。当 Square 已启用，但所选模式缺少 Application ID、Access Token 或 Location ID 时（此时结账页面会隐藏该付款方式），当 Square 无法处理您店铺的默认货币时，以及当 Square 地点的货币与之不一致时，页面都会发出提醒。若您没有修改扩展的权限，页面仍会显示设置，但无法保存。
保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数（允许负数），Total 必须为 0 或更大的数字，且所选的地区（geo zone）和订单状态必须存在；否则不会保存任何内容。随后，扩展会与 Square 核对所选模式的凭据。无论如何设置都会被保存，警告会以红色区块显示在设置上方：Square 拒绝了 Access Token，该令牌找不到对应的 Location ID，无法核对凭据，或地点货币与店铺货币不一致。Square 只能以地点货币扣款：扩展会记住已核对地点的货币，并对其他货币的订单隐藏该付款方式。如果在正式模式中使用了沙盒 Application ID，或反之，扩展也会发出警告。
Square
Enable/Disable：Enable Square Payment Gateway 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称，也是订单中保存的付款方式名称。默认：Credit / debit card。必填。
Description：顾客在 Confirm Order 步骤中、银行卡表单上方看到的文字。默认：Pay securely with your credit or debit card via Square.
Sort Order：银行卡付款在结账时付款方式中的排列位置。可留空或填写整数（允许负数）。
Geo Zone：仅对所选地区内的付款地址显示银行卡表单。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。
Total：订单在结账时必须达到的金额（以店铺默认货币计）才会提供该付款方式。留空则对任何金额都提供。
Square 账户
打开 Square Developer Dashboard（该部分提供了链接），选择您的应用，从 Credentials 页面复制 Application ID 和 Access token（Sandbox 与 Production 的值是分开的），并从 Locations 页面复制 Location ID。地点的货币必须与您店铺的货币一致。页面只显示所选模式的凭据字段：Sandbox Mode 开启时显示沙盒字段，关闭时显示正式环境字段。两组字段都会保持保存状态。
Sandbox Mode：付款会发送到 Square 沙盒，不会扣除真实资金。请使用 Square 测试卡。默认：开启。订单的退款始终使用该订单付款时所在的环境和地点。
Sandbox Application ID：您的 Square 沙盒 Application ID（以 sandbox-sq0idb- 开头）。
Sandbox Access Token：您的 Square 沙盒 Access Token。
Sandbox Location ID：您的 Square 沙盒 Location ID。
Live Application ID：您的 Square 正式环境 Application ID（以 sq0idp- 开头）。
Live Access Token：您的 Square 正式环境 Access Token。
Live Location ID：您的 Square 正式环境 Location ID。
已保存的 Access Token 不会再次显示。该字段会保持为空，并显示 已保存——留空即保持不变。。只有在需要更改时才输入新值。如要删除已保存的 Access Token，请勾选字段下方的 Clear the saved value on save，然后点击 Save。
订单
OpenCart 在 Confirm Order 步骤创建订单时不带状态（即未完成的订单）。只有在 Square 响应付款之后，订单才会获得状态。下方每个字段都列出了您的 OpenCart 订单状态。
Order Status After Payment：Square 已完成与订单金额和货币完全一致的付款。默认：Processing。
On Hold (Review) Status：付款需要您审核（参见订单状态）。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。
Refunded Status：在订单页面将付款全额退款后设置。默认：Refunded。
高级
Debug log：错误和警告始终会被记录。开启后，还会将每个请求和响应（不含银行卡数据和密钥）记录到 OpenCart 日志文件夹（storage/logs）中的 wc_sqg_debug.log.php。该文件无法通过网页打开；当其达到 5 MB 时，会被移动为 wc_sqg_debug.old.log.php。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启后，卸载扩展时会删除网关设置和日志文件。订单的 Square 付款和退款始终会保留。默认：关闭。
导入 / 导出
Export：Download JSON 将设置保存为 JSON 文件。Access Token 不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的 Access Token 会保留。
结账
在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit / debit card）。在 Confirm Order 步骤中，顾客会看到 Credit / debit card (Square)、您填写的描述、沙盒模式开启时显示的 沙盒模式——不会产生真实扣款。，以及 Square 银行卡表单。OpenCart 在此步骤创建订单，此时仍无状态。顾客点击 Confirm Order 后，银行卡会在浏览器中经买家验证（3-D Secure / SCA）后被令牌化：订单金额、货币和付款地址会发送给 Square，顾客的银行可能要求确认。您的店铺只会收到一次性令牌。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式。随后，Square 银行卡表单会出现在结账页面底部的确认区块中，位于 Confirm Order 上方。
随后，扩展会通过 Square Payments API 按订单货币对订单金额扣除该令牌，并以订单号作为参考，附带一条含订单号和店铺名称的 Order # 备注，以及顾客的电子邮件。付款会立即扣款。只有在 Square 确认后，订单才会被标记为已付款：Square 的响应必须显示一笔 COMPLETED 状态的付款，且其金额、货币、订单号和地点与订单完全一致。之后，订单会以 OpenCart 的标准方式获得 Order Status After Payment，并发送常规的订单邮件、更新库存，顾客会看到 OpenCart 订单成功页面，其中显示 我们已收到您的银行卡付款。，以及一个指向 Square 收据的链接 View the receipt。如果付款不是 COMPLETED 或任一数值不一致，订单会获得 On Hold (Review) Status，页面会显示 我们已收到您的银行卡付款，目前正在审核。审核完成后，我们会尽快更新您的订单。
每个购物车同一时间只会执行一次付款尝试。如果顾客点击两次，或在两个标签页中付款，第二次尝试会看到 该订单正在付款中。请稍等片刻，并在再次尝试前检查您的电子邮件。。请求具有幂等性，而且每次显示 Confirm Order 步骤时 OpenCart 3 都会创建一个新订单，因此扩展会跟踪购物车：已付款的购物车绝不会再次扣款，顾客会直接进入成功页面。
如果 Square 没有响应（网络问题、超时、服务器错误），请求会使用相同的幂等键重试一次。如果仍无响应，扩展会立即在 Square 中查找该订单的付款。若找到，订单会据此获得状态。若找不到付款，顾客会停留在 Confirm Order 步骤，并看到 无法从付款服务商获得确认。请稍等一分钟后重试——如果您的银行卡已被扣款，系统会识别该付款，您不会被重复扣款。 同一购物车的下一次尝试会先重新查找之前的付款。如果此次查找也无法连接 Square，订单会获得 On Hold (Review) Status（无付款），并附带备注说明银行卡可能已被扣款，成功页面会显示 无法从 Square 确认您的银行卡付款。请先检查您的电子邮件和银行卡对账单，再重新付款，或与我们联系。
如果银行拒绝银行卡，订单会保持无状态，顾客会停留在 Confirm Order 步骤，并根据 Square 的错误代码看到简短提示，例如 您的银行卡被拒绝。请使用其他银行卡或付款方式。、银行卡安全码（CVV）不正确。请检查后重试。 或 您的银行要求额外验证（3-D Secure）。请重新输入银行卡并完成验证。 购物车会保留，顾客可以更换其他银行卡再次尝试。技术原因会记录到日志中。
OpenCart 4 为结账保留一个订单并对其进行更新，因此银行卡被拒后，顾客会再次支付同一订单；如果未收到 Square 的响应，该订单的下一次尝试会先查找之前的付款。如果结账中的订单已有状态（已付款或已被店铺关闭），且购物车中包含新商品，顾客会被带回结账页面，新购物车将以新订单完成付款。
该扩展仅接受银行卡付款，且会立即扣款。它不支持保存的银行卡或顾客档案、订阅、Apple Pay、Google Pay、Cash App Pay、Afterpay、ACH 或 Square 礼品卡，不支持仅授权付款，不使用 Square Webhook，也不与 Square 同步商品或库存。争议需在 Square Dashboard 中处理。
订单与退款
订单状态
无状态（未完成订单）：顾客尚未付款，银行卡被拒绝，或 Square 的响应丢失且未找到付款。在 Sales > Orders 中，此类订单仅在 Order Status 筛选器设为 Missing Orders 时才会显示。
Order Status After Payment（默认 Processing）：Square 已确认订单金额的 COMPLETED 付款。备注会显示 Square 付款 ID、银行卡品牌及后 4 位数字，以及模式（沙盒或正式）。
On Hold (Review) Status（默认 Pending）：Square 返回的付款不是 COMPLETED（例如 APPROVED 或 PENDING），或金额、货币、参考号或地点与订单不一致。备注 Square 付款需要审核 会显示付款 ID、状态和金额。当订单在付款期间发生变化，以及当 Square 的响应丢失且无法核实时（此时不会记录付款，备注会要求您使用订单号作为参考，在 Square Dashboard 中核对该地点的付款），也会使用此状态。发货前请在 Square Dashboard 中核实付款。
Refunded Status（默认 Refunded）：付款已通过该扩展全额退款。
如果对已有已付款订单的购物车再次付款，已付款订单不会被更改。备注会提示您检查该情况，并在 Square Dashboard 中退还重复的付款。
备注是订单 History 中的条目，顾客看不到。
VibeFox Square Gateway 标签页
在 Sales > Orders 中打开一笔通过 Square 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox Square Gateway 标签页会显示 Square 的 Payment ID（链接到 Square Dashboard 中的付款），沙盒付款会带有 Sandbox 标签；此外还显示 Square 的 Status、Card 品牌及后 4 位数字、Paid / order / refunded 金额、Environment / location、Square receipt 链接、退款表单、退款历史以及订单的 Square notes。银行卡号码绝不会被存储。该标签页仅对有权访问该扩展的用户显示。
退款
在 VibeFox Square Gateway 标签页中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Square。确认提示 是否通过 Square 退还此金额？此操作无法撤销。。支持全额和部分退款。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。退款以 Square 扣款时的金额和货币进行，因此金额不一致时，您最多可以退还顾客实际支付的金额，而不是订单总额。退款会发送到付款时所在的环境（沙盒或正式）和地点，因此必须设置该模式的 Access Token。退款请求具有幂等性，若 Square 无响应会重试一次。Square 接受的退款（状态为 PENDING 或 COMPLETED）会连同 Square 退款 ID 添加到退款历史和备注中。若 Square 拒绝，标签页会显示错误，且不会记录退款。全额退款会将订单设为 Refunded Status，不会通知顾客，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。
Sales > Returns 中的商品退货不会通过 Square 退款。Square 在其自身一侧完成退款：Square 之后拒绝的退款不会回传，并且在 Square Dashboard 中完成的退款也不会显示在 OpenCart 中。
许可证密钥
该扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥才能运行。许可证区块 License — VibeFox Square Gateway 位于 Extensions > Extensions > Payments > VibeFox Square Gateway > Edit 页面的最上方，在设置之前。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥，并显示状态（例如许可证有效期截止日期及您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入另一个密钥，Remove key 用于从此店铺移除该密钥。其下方是 Product: opencart-payment-square 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加日期。在店铺地址变更后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账页面不会向顾客显示 Square。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one.。在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该付款方式，并带有 (unlicensed — visible to admins only) 标记，因此您可以在购买密钥前完成扩展的设置与测试。在 OpenCart 4 中没有此预览功能：店铺无法看到后台登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已付款订单仍为已付款，退款也照常可用。
许可证过期后，扩展会继续运行，但更新和支持需要续期。当您打开后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，许可证密钥和许可证状态总会被删除。
故障排除
Square 未在结账页面中显示：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式的 Application ID、Access Token 和 Location ID 是否已填写。检查顾客的货币是否为 USD、CAD、AUD、JPY、GBP 或 EUR，并与您 Square 地点的货币一致。设置页面会针对上述每个问题显示警告。另外还需检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。
银行卡表单无法加载：顾客会看到 无法加载银行卡表单。请刷新页面或选择其他付款方式。。请检查 Application ID 和 Location ID 是否属于所选模式（沙盒 ID 以 sandbox- 开头）。如果顾客点击得过早，会显示 银行卡表单仍在加载中。请稍候片刻后重试。
保存后付款方式消失：Square 地点的货币与订单货币不一致。请输入一个与您店铺货币相同的 Square 地点的 Location ID，然后重新保存：经过成功核对后，该付款方式会再次显示。
Square 拒绝了所选模式的 Access Token：该令牌属于另一模式或填写有误。请从应用的 Credentials 页面重新复制，并检查 Sandbox Mode。
该 Access Token 找不到对应的 Location ID：请从同一应用、同一模式的 Locations 页面复制 Location ID。
顾客看到了 无法从付款服务商获得确认：Square 没有响应，且尚未找到付款。请在 Square Dashboard 中检查该地点的付款（参考号 = 订单号）。如果顾客再次尝试，扩展会先查找之前的付款并使用它，而不是再次扣款。
顾客看到了 您的付款已收到，但订单无法自动完成：银行卡已被扣款，但 OpenCart 无法设置订单状态。请阅读日志，然后手动完成订单，或在 Square Dashboard 中退款。
顾客看到了 此付款方式不适用于您的订单：结账内容已与订单不匹配，付款方式可能已在此期间关闭，或订单货币无法扣款。顾客可以刷新结账页面或选择其他付款方式。
订单在付款后处于审核状态：请阅读 VibeFox Square Gateway 标签页中的备注（参见订单状态）。在 Square Dashboard 中核实付款，然后完成订单或退款。
标签页中没有退款表单：标签页会说明原因：没有 Square 付款为该订单扣款，未记录 Square 付款 ID（此时标签页会指明需要在 Square Dashboard 中查找的地点和订单号），付款已全额退款，或您的用户组没有修改扩展的权限。
退款因模式相关的消息而失败：付款是在沙盒或正式模式下进行的，而该模式的 Access Token 未设置。请输入后重试。
其他错误：开启 Debug log，并查看扩展页面上的 Log 字段。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Square Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分中的订单状态，这些在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除。如果 Delete data on uninstall 已开启，则其余网关设置（标题、描述、沙盒模式、凭据、日志）和日志文件都会被删除。如果已关闭，这些内容会保留，供日后重新安装使用。订单的 Square 付款和退款始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 中，如需删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Square Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Square 是其各自所有者的商标。本扩展与 Square 无关联，也未获得 Square 的认可或背书。