VibeFox PayPlug for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
货币和金额：欧元（EUR），每笔付款 0.99 至 20,000.00，即 PayPlug 的默认值。欧元必须在 System > Localisation > Currencies 中启用，并由顾客选择。若结账货币不是欧元，或金额超出这些限制，则会隐藏该付款方式。
PayPlug 账户：您需要 PayPlug 账户的密钥：测试密钥（sk_test_...）和/或正式密钥（sk_live_...）。不需要其他密钥，也无需在 PayPlug 中设置任何通知。您的店铺必须能从互联网访问才能接收通知；否则，订单会在顾客从 PayPlug 返回时被确认。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只适用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_payplug_gateway-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 wcp_payplug_gateway.ocmod.zip。只需安装适用于您 OpenCart 版本的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_payplug_gateway-oc3-(version).ocmod.zip。本扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayPlug Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改付款扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。在页面顶部许可证区块的 License key 中输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 粘贴您从 PayPlug 后台获取的密钥（参见配置）。
5. 开启 Enable/Disable，然后点击 Save。在 Test Mode 开启的情况下测试一笔付款，之后将其关闭以接收真实付款。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_payplug_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayPlug Gateway，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥和 PayPlug 密钥。两个版本的设置页面及其字段相同。只有通知 URL 不同（参见通知）。
新安装时，付款方式默认关闭，测试模式默认开启。
配置
所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox PayPlug Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果付款方式已启用但当前模式的密钥为空，或店铺默认货币不是 EUR，页面会发出警告。在这两种情况下，结账时都会隐藏该付款方式（若默认货币不同，则在选择该货币时隐藏）。若没有修改扩展的权限，页面会显示设置，但无法保存。
保存时，Title 必须为 1 至 128 个字符，Sort Order 必须为整数，Total 必须为 0 或更大的数字，且订单状态必须存在；否则不会保存任何内容，页面会列出错误。格式错误的密钥不会被保存，但其他设置会被保存：页面会显示 Settings saved, except the secret key shown in red.，例如 Test Secret Key must start with "sk_test_". The previous value was kept.
Checkout
Enable/Disable：Enable PayPlug Gateway 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：PayPlug。必填，最多 128 个字符。
Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely by card via PayPlug。
Sort Order：PayPlug 在结账付款方式中的位置。留空或输入整数。
Geo Zone：仅对所选地理区域内的付款地址提供 PayPlug。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total：订单须达到的结账总额（以店铺默认货币计）才会提供 PayPlug。留空则对任何金额都提供 PayPlug。PayPlug 本身接受每笔 0.99 至 20,000.00 EUR 的付款。
API 密钥
您可以在 PayPlug 后台的 Developers > API keys 下找到您的密钥。该部分包含后台的链接。
Test Mode：新付款使用测试密钥。不会处理任何真实付款。在另一种模式下进行的付款，在查询状态和退款时仍使用其所属模式的密钥。默认：开启。开启时，顾客在 Confirm Order 步骤会看到 Test mode: no real payment will be made.
Test Secret Key：您的 PayPlug 测试密钥，以 sk_test_ 开头。
Live Secret Key：您的 PayPlug 正式密钥，以 sk_live_ 开头。
已保存的密钥不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的密钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。
通知
Notification URL：扩展随每笔付款发送给 PayPlug 的地址。OpenCart 3 的格式类似 https://your-store/index.php?route=extension/payment/wcp_payplug_gateway/webhook，OpenCart 4 的格式类似 https://your-store/index.php?route=extension/wcp_payplug_gateway/payment/wcp_payplug_gateway.webhook，根据您 OpenCart 安装的店铺地址生成。无需在 PayPlug 后台填写任何内容。每条通知都会通过 PayPlug API 重新读取付款信息进行核对，因此即使顾客没有返回店铺，付款也会被确认。该 URL 必须能从互联网访问；否则，订单只会在顾客从 PayPlug 返回时被确认。
订单
OpenCart 在 Confirm Order 步骤创建订单时不带状态（即缺失订单）。只有在 PayPlug 通过通知或顾客返回报告付款后，订单才会获得状态；付款信息始终会从 PayPlug 重新读取。下面的每个字段都列出了您的 OpenCart 订单状态。
Order Status After Payment：付款成功后设置的状态，例如 Processing 或 Complete。默认：Processing。
PayPlug Payment On Hold Status：付款需要您审核（参见订单状态）。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。
Payment Error Status：待处理订单的已授权付款失败或被取消。默认：Failed。
Refunded Status：在订单页面全额退款后设置。默认：Refunded。
高级
Logging：将 API 调用和通知记录到 OpenCart 日志文件夹（storage/logs）中的 ppg_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。密钥、银行卡数据和顾客数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete Data on Uninstall：开启后，卸载扩展时会删除扩展设置及其日志。订单中的 PayPlug 付款和退款记录始终保留。默认：关闭。
导入 / 导出
Export：Download JSON 将设置保存为 JSON 文件。密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的密钥会被保留。
结账
在 Payment Method 步骤中，顾客选择付款方式（默认为 PayPlug）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to the secure PayPlug payment page to pay by card.；在测试模式下，还会看到 Test mode: no real payment will be made. OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客通过支付方式区块中的 Choose 按钮、在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。当顾客点击 Confirm Order 时，扩展会为订单总额（以分计）创建一笔 PayPlug 付款，并将顾客转到 PayPlug 付款页面。账单和配送地址、电子邮件以及订单语言会被传递给 PayPlug。顾客在那里用银行卡付款。
付款后，顾客返回您的店铺。只有在 PayPlug 确认付款后，订单才会被标记为已付款：扩展会在通知到达时以及顾客返回时，通过 PayPlug API 读取付款信息。然后，订单以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面，并显示 Your payment with PayPlug has been received. 如果订单处于待处理状态，页面会显示 We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. 如果订单处于付款错误状态，页面会显示 Your PayPlug payment was not completed. Please contact us about this order. 如果顾客返回时无法向 PayPlug 查询，则会显示 Payment confirmation 页面，其中包含相同的“正在确认”文字和 Check again 按钮；通知一到达就会设置订单状态。
如果顾客在 PayPlug 页面取消，付款页面会在 PayPlug 端被关闭，因此无法在之后误付。顾客会回到结账页面，并看到以下提示之一：You cancelled the PayPlug payment. You can try again or choose another payment method.、The PayPlug payment session has expired. Please try again or choose another payment method.、The PayPlug payment failed. Please try again or choose another payment method.，或者如果付款仍处于打开状态，则为 Your PayPlug payment was not completed. You can try again or choose another payment method. 购物车会被保留。在 OpenCart 4 中，这些提示会显示在结账页面上方。
OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，而 OpenCart 4 则会更新结账订单（新的尝试即同一订单的新 PayPlug 付款），因此扩展会先检查同一购物车的较早尝试。如果其中某次在此期间已被付款，则直接使用该笔付款，不再新建付款，顾客会进入成功页面。如果本订单的尝试仍处于打开状态且金额相同，则会再次使用同一付款页面。否则，旧页面会在 PayPlug 端被关闭，并创建新的付款。对已关闭页面的迟到付款仍会被记录。购物车的任何变化（包括数量变化）都视为需要单独付款的新购物车。
在 OpenCart 4 中，订单会一直停留在结账流程中，直到显示成功页面。如果该订单期间已在未付款的情况下被关闭（例如您取消了它，或其已授权的付款失败），顾客会带着 Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order. 提示返回结账页面。下一次 Confirm Order 将支付一个新订单。如果该订单此前已为某个购物车付款，且购物车之后发生了变化，顾客会被带回结账页面，下一次 Confirm Order 将为当前购物车支付一个新订单。已关闭的订单绝不会显示为已付款。
如果 PayPlug 无法发起付款，顾客会停留在 Confirm Order 步骤，并看到简短提示，例如 PayPlug could not accept your billing details (postcode). Please check them and try again. 或 The payment provider could not be reached. Please try again in a moment. 具体的技术原因会写入日志。
即使店铺处于维护模式，通知仍然有效，因为 OpenCart 允许付款扩展的请求通过（在 OpenCart 4 中，扩展会为此添加自己的启动动作，该动作同时允许顾客从 PayPlug 返回）。
付款会立即扣款。本扩展不支持 Oney 分期、一键保存卡、嵌入式付款表单、订阅或延迟扣款。
订单与退款
订单状态
无状态（缺失订单）：顾客已被转到 PayPlug 但尚未付款，或 PayPlug 尚未确认付款。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时才会显示此类订单。如果付款失败，该尝试会被关闭，顾客可以再次付款。
Order Status After Payment（默认 Processing）：付款已确认。备注中会显示 PayPlug 付款及其模式。
PayPlug Payment On Hold Status（默认 Pending）：已付金额或货币与订单不符（备注 amount/currency mismatch）；或店铺处于正式模式时收到了测试付款，因此实际上没有收到款项；或付款是在订单已获得其他状态（例如已被取消）之后才到达的；或付款已授权但尚未扣款（请在 PayPlug 后台进行扣款；当 PayPlug 报告付款为已付款时，订单会被标记为已付款）。备注会说明需要检查的内容。
Payment Error Status（默认 Failed）：待处理订单的已授权付款失败或被取消。OpenCart 会将此变更通知顾客。
Refunded Status（默认 Refunded）：付款已通过本扩展全额退款。
如果某个已付款购物车的另一笔订单也被付款，该订单将保持无状态，已付款订单不会被更改。已付款订单上的备注会要求您在 PayPlug 后台退还重复付款。已付款或已退款的订单绝不会因之后的通知而重新打开。
备注是订单 History 中的条目，顾客看不到。
VibeFox PayPlug Gateway 选项卡
在 Sales > Orders 中打开一笔通过 PayPlug 付款的订单。在订单页面底部、History 和 Additional 旁边，VibeFox PayPlug Gateway 选项卡会显示 PayPlug payment ID（测试付款会附带 Test mode 标签）、付款 Status、Paid / refunded 金额、退款表单、退款历史（包括每笔退款的模式）以及订单的 PayPlug notes。该选项卡只显示给有权访问本扩展的用户。
退款
在 VibeFox PayPlug Gateway 选项卡中输入 Amount（未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via PayPlug。确认提示 Refund this amount through PayPlug? This cannot be undone. 支持全额和部分退款。您需要有修改本扩展的权限（在 System > Users > User Groups 中设置）。退款金额最高为 PayPlug 实际收取的金额，因此在出现金额不符的情况下，您可以退还顾客实际支付的金额，而不是订单总额。退款会使用发起该退款时所处模式（测试或正式）的密钥，退给实际支付订单的那笔付款，因此该模式的密钥必须已设置。如果 PayPlug 不接受退款，选项卡会显示错误，且不会记录任何退款。成功的退款会连同 PayPlug 退款 ID 和原因一起添加到退款历史和备注中。全额退款会将订单设为 Refunded Status，但不会通知顾客，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。一旦 PayPlug 报告付款为已付款，即可进行退款。
在 Sales > Returns 中的商品退货不会通过 PayPlug 退还款项。
在 PayPlug 后台进行的退款会通过通知到达，并且只会添加到备注中一次。它们会列在退款历史中，但不计为本扩展的退款，也不会更改订单状态。如有需要，请手动记录。
许可证密钥
本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。扩展的 Edit 页面顶部、设置上方有一个许可证区块 License — VibeFox PayPlug Gateway，它是该区块中的第一个。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-payment-payplug 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有对本扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包含英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。在店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用上次已知的状态运行。
一个密钥只适用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，PayPlug 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥前设置并测试扩展。在 OpenCart 4 中，此预览不可用：店铺无法看到后台登录状态，因此没有有效密钥时，该付款方式对所有人都隐藏。您打开过一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其关闭，关闭后 7 天内不再显示。现有订单不受影响：已发起的付款仍会被确认，退款功能也仍可使用。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
结账时未显示 PayPlug：请检查许可证是否有效、Enable/Disable 是否开启、当前模式是否已设置密钥（测试模式为 Test Secret Key，正式模式为 Live Secret Key）、结账货币是否为 EUR，以及订单金额是否在 0.99 至 20,000.00 EUR 之间。还请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。开发人员可以通过 OpenCart 事件 ppg_supported_currencies 和 ppg_amount_limits（以分为单位的值）更改货币和限额，并通过 ppg_payment_data 修改付款请求。
付款已完成，但订单仍无状态：通知未到达您的店铺，且顾客也没有返回。请检查设置中显示的 Notification URL 是否可从互联网访问，例如是否有防火墙或密码保护将其拦截。开启 Logging，并在 Log 字段中查看被拒绝的通知。
通知返回 Verification failed.：无法通过 PayPlug API 读取付款，例如 PayPlug 没有响应，或付款所属模式的密钥未设置。订单不会被更改，PayPlug 会重新发送通知。
通知返回 Temporarily unavailable.：购物车在同一时刻正被另一请求（例如顾客返回）更新，或无法设置订单状态。PayPlug 会重新发送通知。日志会显示原因。
通知返回 Unknown payment. 或 Payment does not belong to the order.：该付款不是由本店铺创建的，或不属于此订单，例如同一 PayPlug 账户上另一店铺的付款。该通知会被忽略。
通知 URL 在浏览器中显示 Method not allowed.：这是正常现象。该 URL 只接受来自 PayPlug 的请求。
顾客在 Confirm Order 后看到错误：开启 Logging 并查看 Log 字段。密钥错误会显示 This payment method is temporarily unavailable. Please choose another payment method.；其他消息会指出 PayPlug 拒绝的账单字段。
顾客返回后看到 Payment verification failed.：返回链接与订单的任何付款尝试都不匹配，例如它是在另一个浏览器中打开的。请在 PayPlug 后台检查该付款；通知仍会设置订单状态。
付款后订单处于待处理状态：请阅读 VibeFox PayPlug Gateway 选项卡中的备注（参见订单状态），然后处理订单或退还付款。
选项卡中没有退款表单：选项卡会说明原因：付款尚未完成、已全额退款、您的用户组没有修改扩展的权限，或付款所属模式的密钥未配置。
退款失败并显示 Unexpected response from PayPlug.：PayPlug 返回的结果不是有效的退款。未记录任何内容。再次尝试之前，请先在 PayPlug 后台检查该退款。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox PayPlug Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还会删除其事件以及允许维护模式下通知和顾客返回通过的启动动作）。如果 Delete Data on Uninstall 已开启，其他设置（标题、描述、测试模式、密钥、日志）和日志都会被删除。如果已关闭，它们会被保留，以便日后重新安装时使用。PayPlug 付款和退款记录始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 中，若还要删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox PayPlug Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
PayPlug 是其各自所有者的商标。本扩展与 PayPlug 没有关联，也未获得 PayPlug 的认可。