VibeFox PayPlug for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在更旧的 PHP 版本上安装。
币种和金额：欧元（EUR），每笔付款 0.99 至 20,000.00，即 PayPlug 默认值。购物车币种不同或超出这些限制时，付款方式会被隐藏。
PayPlug 账户：您需要 PayPlug 账户的密钥：测试密钥（sk_test_...）和/或正式密钥（sk_live_...）。不需要其他密钥，也无需在 PayPlug 中设置任何通知。您的商店必须可以从互联网访问才能接收通知；否则，订单会在顾客从 PayPlug 返回时创建。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox PayPlug Gateway，点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。
4. 从 PayPlug 门户粘贴您的密钥（参见配置）。
5. 开启 Enable/Disable，点击 Save。在开启 Test Mode 的情况下测试一笔付款，然后关闭它以接受真实付款。
安装时，模块会创建订单状态 PayPlug payment on hold。PrestaShop 会为所有币种、国家和客户组启用新的付款模块。您可以在 Payment > Preferences 中进行限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox PayPlug Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果已启用付款方式但当前模式的密钥为空，或商店的默认币种不是 EUR，页面都会发出警告。在这两种情况下，结账时都会隐藏该付款方式。
结账
Enable/Disable：Enable PayPlug Gateway 用于开启或关闭付款方式。默认值：off。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认值：PayPlug。必填。
Description：结账时显示在付款方式下方的文字。默认值：Pay securely by card via PayPlug。
API 密钥
您可以在 PayPlug 门户的 Developers > API keys 下找到密钥。该部分包含门户链接。
Test Mode：新付款使用测试密钥。不会处理任何真实付款。在另一模式下进行的付款，在状态查询和退款时仍使用其所属模式的密钥。默认值：on。开启时，顾客会在付款方式下方看到 Test mode: no real payment will be made.
Test Secret Key：您的 PayPlug 测试密钥。以 sk_test_ 开头。
Live Secret Key：您的 PayPlug 正式密钥。以 sk_live_ 开头。
前缀错误的密钥不会被保存。页面会显示例如 Test Secret Key must start with "sk_test_". The previous value was kept. 已保存的密钥不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Clear saved keys：勾选某个密钥并点击 Save 即可将其删除。空字段会保留已保存的值。
Notification URL：模块随每笔付款发送给 PayPlug 的地址。启用友好 URL 时，它类似于 https://your-shop/module/wcp_payplug_gateway/webhook。无需在 PayPlug 门户中填写任何内容。该 URL 必须可以从互联网访问；否则，订单会在顾客从 PayPlug 返回时创建。
订单
Order Status After Payment：付款成功后设置的订单状态。状态会立即设置，无需第二次状态变更。
高级
Logging：将 API 调用和通知记录到模块文件夹中的 logs/ppg_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。密钥、银行卡数据和顾客数据绝不会被记录。默认值：off。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete Data on Uninstall：开启后，卸载模块时会删除模块设置及其日志。订单中保存的 PayPlug 付款 ID 和 PayPlug payment on hold 订单状态会被保留。默认值：off。
结账
在付款步骤，顾客选择付款方式（默认为 PayPlug，带有 PayPlug 标志）。在测试模式下，该选项会显示 Test mode: no real payment will be made. 确认后，模块会以分为单位为购物车总额创建一笔 PayPlug 付款，并将顾客引导至 PayPlug 付款页面。账单地址和收货地址、电子邮件和购物车语言会被传递给 PayPlug。顾客在那里用银行卡付款。此时尚未创建订单。
付款后，顾客返回您的商店。只有在 PayPlug 确认后，订单才会被标记为已付款：模块会在通知到达时以及顾客返回时，通过 PayPlug API 读取付款信息。随后订单被创建，顾客会看到标准订单确认页面，并显示 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. 如果订单处于 Payment error 状态，或在未付款的情况下被取消，页面会显示 Your PayPlug payment was not completed. Please contact us about this order. 如果顾客返回时无法向 PayPlug 查询，Payment confirmation 页面会显示相同的“we are confirming”文字以及 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. 购物车会被保留。
当顾客再次支付同一购物车时，模块会先检查上一次尝试。如果其间已付款，则直接创建订单，无需新的付款。如果该付款仍以相同金额处于打开状态，则再次使用同一付款页面。否则，旧页面会在 PayPlug 端关闭，并创建新的付款。
如果 PayPlug 无法启动付款，顾客会停留在结账页面，并看到简短提示，例如 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. 技术原因会被写入日志。
即使商店处于维护模式，通知仍会正常工作，且不受商店国家限制的影响。
付款会立即扣款。本模块不支持 Oney 分期、一键保存卡片、嵌入式付款表单、订阅或延迟扣款。
订单与退款
订单状态
No order yet：顾客已被引导至 PayPlug 但尚未付款，或 PayPlug 尚未确认付款。此时仅存在购物车。
Payment accepted or Delivered：付款已确认。状态遵循 Order Status After Payment。付款会以 PayPlug 付款 ID（pay_...）作为交易 ID 记录，并且备注会显示该 PayPlug 付款及其模式。
PayPlug payment on hold：已付金额或币种与购物车不一致（备注 amount/currency mismatch，例如付款开始后购物车被修改）；或在商店处于正式模式时进行了测试付款，因此未收到任何款项，也不会记录付款；或付款针对的是已取消的订单；或付款已授权但未扣款（请在 PayPlug 门户中扣款；当 PayPlug 报告付款已完成时，订单会被标记为已付款）。备注会说明需要检查的内容。
Payment error：保留订单的已授权付款失败或被取消。
Refunded：付款已通过模块全额退款。
如果对已付款购物车的第二次尝试也完成了付款，订单不会被更改。备注会提示您在 PayPlug 门户中退还重复付款。已付款、已取消或已退款的订单绝不会因后续通知而重新打开。
PayPlug 付款区块
订单页面显示 PayPlug payment 区块，包括 PayPlug 付款 ID、付款状态、已付和已退款金额、测试付款的 Test mode 标记、退款记录以及订单的 PayPlug notes。
退款
在 PayPlug payment 区块中输入金额（未退款金额会自动填入），可选填写原因，然后点击 Refund via PayPlug。确认提示 Refund this amount through PayPlug? This cannot be undone. 支持全额和部分退款。您需要具备编辑订单的权限；无需访问模块页面。退款金额以 PayPlug 实际扣款的金额为限，因此在金额不一致的情况下，您可以退还顾客实际支付的金额，而不是订单总额。退款会通过实际支付该订单的付款进行，并使用退款时所在模式（测试或正式）的密钥，因此该模式的密钥必须已设置。如果 PayPlug 拒绝退款，区块会显示错误，并且不会记录任何退款。成功的退款会连同 PayPlug 退款 ID 和原因一起添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会更改状态。只有在 PayPlug 报告付款已完成之后，才可以退款。
模块不会创建退款单。订单页面上的标准 PrestaShop 退款按钮不会通过 PayPlug 退款。
在 PayPlug 门户中进行的退款会通过通知到达，并且只会添加到备注中一次。它们不计入该区块，也不会更改订单状态或退款单。如有需要，请手动记录。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox PayPlug Gateway 许可证区块位于 Modules > Module Manager > VibeFox PayPlug Gateway > Configure 页面的第一个区块，位于设置上方。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now 用于再次检查状态，Change key 用于输入其他密钥，Remove key 用于从此商店中删除密钥。其下方是 Product: presta-payment-payplug 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上一个日期。商店地址更改后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用最后已知的状态运行。
一个密钥只能用于一个域名：主商店的域名，多店铺配置中也是如此。从商店中删除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 PayPlug。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法知道您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡会出现提醒。现有订单不受影响：已发起的付款仍会被确认，退款也仍可进行。
许可证过期后，模块仍会继续运行，但更新和支持需要续期。在后台工作时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 PayPlug：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式是否设置了密钥（测试模式为 Test Secret Key，正式模式为 Live Secret Key）、购物车币种是否为 EUR，以及购物车总额是否在 0.99 至 20,000.00 EUR 之间。在 Payment > Preferences 中，请检查模块是否允许购物车币种、顾客所在国家和顾客所属客户组。开发人员可以通过钩子 actionWcpPayplugSupportedCurrencies 和 actionWcpPayplugAmountLimits 修改币种和限额（以分为单位的值）。
付款已完成，但未创建订单：通知未到达您的商店，而且顾客也没有返回。请检查您的商店是否可以通过设置中显示的 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 的请求。
顾客选择 PayPlug 时看到错误：开启 Logging 并查看 Log 字段。密钥错误会显示 This payment method is temporarily unavailable. Please choose another payment method.；其他消息会指出 PayPlug 拒绝的账单字段。
付款后订单处于 PayPlug payment on hold 状态：请阅读 PayPlug payment 区块中的备注（参见订单状态），然后处理订单或退款。
退款因模式相关的消息失败：付款是在测试或正式模式下进行的，而该模式的密钥未配置。请输入该密钥后重试。
退款因 Unexpected response from PayPlug. 失败：PayPlug 的响应中没有有效的退款。未记录任何内容。请在 PayPlug 门户中检查该退款，然后再重试。
卸载
进入 Modules > Module Manager，打开 VibeFox PayPlug Gateway 旁边的菜单，选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。PayPlug 付款和退款记录以及 PayPlug payment on hold 订单状态始终会被保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注和交易 ID。
PayPlug 是其各自所有者的商标。本模块与 PayPlug 没有关联，也未获得 PayPlug 的认可。