VibeFox Worldline for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。
Worldline 账户：一个 Worldline Direct（原 Ingenico Direct）商户账户。测试和正式账户相互独立，凭据各不相同。每个账户都需要商户 ID（您的 PSPID）、一个 API Key ID 及其 Secret API Key，以及一个 Webhook 密钥及其 secret。所有这些都在 Worldline Merchant Portal 中创建（参见配置）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Worldline Gateway 并点击 Configure。
3. 将您的 VibeFox 许可证密钥粘贴到 Configure 页面顶部许可证区块的 License key 中，然后点击 Activate（参见许可证密钥）。
4. 输入测试凭据，点击 Save，然后点击 Test credentials。
5. 在测试账户的 Merchant Portal 中添加 Webhook URL，并输入 Webhook 密钥和 secret（参见配置）。
6. 开启 Enable/Disable，进行一次测试付款。然后输入正式凭据，在您的正式账户中重复 Webhook 设置，点击 Live credentials，并关闭 Test Mode。
安装时，模块会创建两个订单状态：Awaiting Worldline capture 和 Worldline payment on hold。PrestaShop 会为当时已启用的国家启用新的支付模块。请在 Payment > Preferences 中检查货币、国家和客户组，并在那里勾选您之后添加的国家。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Worldline Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果当前模式的凭据（Merchant ID、API Key ID、Secret API Key）不完整，页面会发出提醒，因为此时结账时会隐藏该支付方式。测试模式开启时，页面会显示 Test mode is on (pre-production environment): no real money is charged.
Worldline (Ingenico)
Enable/Disable：Enable Worldline Gateway 用于开启或关闭该支付方式。默认：关闭。
Title：顾客在结账时看到的支付方式名称。它也是订单中保存的支付方式名称。默认：Worldline。必填。
Description：结账时显示在支付方式下方的文字。默认：Pay securely via Worldline.
Worldline Direct API
请在测试账户和正式账户的 Worldline Merchant Portal 中获取凭据。您的 PSPID 即为 Merchant ID。Developer > Payment API 用于创建 API Key ID 和 Secret API Key，Developer > Webhooks 用于创建 Webhook 密钥和 secret。该部分包含两个门户和 Worldline 文档的链接。
Test Mode：同时切换 API 端点和凭据。测试模式使用预生产环境和测试凭据，正式模式使用生产环境和正式凭据。默认：开启。要接收真实付款，请将其关闭。测试模式开启时，顾客会在支付方式下方看到 Test mode — no real money is charged.
测试账户（预生产）
Test Merchant ID (PSPID)：您测试账户的 PSPID。
Test API Key ID：在测试账户的 Developer > Payment API 中创建的 API Key ID。
Test Secret API Key：属于该 API Key ID 的 Secret API Key。
Test Webhook Key ID：可选。设置后，只接受使用该密钥发送的 Webhook。
Test Webhook Secret：测试账户的 Webhook secret。用于验证每个 Webhook 的签名。
正式账户（生产）
Live Merchant ID (PSPID)：您正式账户的 PSPID。
Live API Key ID：在正式账户的 Developer > Payment API 中创建的 API Key ID。
Live Secret API Key：属于该 API Key ID 的 Secret API Key。
Live Webhook Key ID：可选。设置后，只接受使用该密钥发送的 Webhook。
Live Webhook Secret：正式账户的 Webhook secret。
已保存的密钥和 Webhook secret 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
Clear saved secrets：勾选某个 secret 并点击 Save 即可删除。字段为空时保留已保存的值。
Check credentials：Test credentials 和 Live credentials 按钮会通过对 Worldline 的测试调用，检查每个账户已保存的凭据。请先保存更改。结果会显示在页面顶部，例如 Test credentials: connection successful.、API credentials are not configured.，或 Worldline 返回的错误。
Webhook
即使顾客没有返回店铺（例如关闭了浏览器，或付款稍后才被确认），Webhook 也会将付款信息通知您的店铺。在 Merchant Portal 中，打开测试账户的 Developer > Webhooks，并添加本部分 Endpoint URL 中显示的 URL。使用友好 URL 时，它的形式类似 https://your-shop/module/wcp_worldline_gateway/webhook，可能带有 /en/ 之类的语言代码。请完全按照设置中显示的样子复制 URL：它必须在不重定向的情况下响应。然后在 Test Webhook Key ID 和 Test Webhook Secret 中输入 Webhook 密钥 ID 和 secret。在正式账户中，使用正式字段进行同样的设置。
模块会自动响应 Worldline 的端点验证请求。它处理付款事件（付款状态变更）和退款事件（退款状态变更）。其他事件会被接受但忽略。没有有效签名的 Webhook 会被拒绝。事件必须使用付款所在账户的 secret 签名，因此测试 Webhook 永远不会确认正式付款。如果 Webhook 来自与签名 secret 所属账户不同的 Merchant ID，它也会被忽略。没有 Webhook 时，只有顾客付款后返回店铺，才会创建订单。
支付页面与订单
Payment page template：在 Merchant Portal 中上传的托管结账模板（变体）名称，可选，例如 SimplifiedCustomPaymentPage。留空则使用 Worldline 默认页面。
Order Status After Payment：Worldline 确认已捕获付款后的订单状态。付款始终以直接销售（授权和捕获）方式请求。
已授权的付款会停留在 Awaiting Worldline capture。金额或货币不一致时，总会进入 Worldline payment on hold。
高级
Logging：将所有 API 请求和 Webhook 写入模块文件夹中的 logs/wlg_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误和警告仍会始终被记录。密钥、银行卡数据和个人数据均已脱敏。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete Data：开启时，卸载模块会删除模块设置和日志。Worldline 交易、退款以及模块的订单状态始终保留，因为现有订单需要它们来处理退款。默认：关闭。
结账
在支付步骤中，顾客选择支付方式（默认为 Worldline）并确认。模块会按购物车金额以购物车货币创建 Worldline 托管结账页面，并将顾客发送到 Worldline 支付页面。顾客在那里使用银行卡、电子钱包或您的 Worldline 账户中已启用的其他支付方式付款。账单姓名、地址、电子邮件和电话会传递给 Worldline，并且当 Worldline 支持顾客的语言时，支付页面会以该语言打开。每次付款尝试都会获得自己的参考号，由购物车 ID 和一段随机字符组成。此时尚未创建订单。
付款后，顾客返回您的店铺。模块会根据已保存的尝试核对返回信息，并在服务器端从 Worldline 读取付款状态。只有在 Worldline 确认后，订单才会被标记为已付款：通过此状态检查，或通过带签名的 Webhook。随后订单会被创建，顾客会看到标准订单确认页面，并显示 Your payment with Worldline has been received. 如果付款已授权但尚未捕获，页面会显示 Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. 如果此类订单之后付款失败，页面会显示 Your Worldline payment was not completed. Please contact us about this order.
如果付款未完成，则不会创建订单，购物车会保留，顾客会带着提示返回结账页面：
如果暂时无法检查付款状态，Payment confirmation 页面会显示 We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it.，并带有 Check again 和 Back to checkout 按钮。Webhook 一到达就会创建订单。
当顾客再次为同一购物车付款时，模块会先检查之前的尝试。如果它在此期间已付款，顾客会直接进入订单确认页面，不会被重复扣款。如果之前的付款页面仍然开启，金额和模式相同，并且创建于 30 分钟以内，顾客会被送回该页面。
如果 Worldline 无法启动付款，顾客会停留在结账页面，并显示 Payment error: Could not create checkout session. Please try again. 原因会写入日志。如果当前模式的凭据缺失，顾客会看到 This payment method is not available at the moment. Please choose another payment method.
即使店铺处于维护模式，Webhook 仍然有效，并且不会受到店铺国家限制的阻挡。
模块在 Worldline 页面上以直接销售方式接受一次性付款。它不支持保存银行卡或令牌化、订阅、嵌入式银行卡表单、在 PrestaShop 中进行仅授权并随后扣款或取消的模式、附加费或自动注册 Webhook。
订单与退款
订单状态
No order yet：顾客已被引导至 Worldline 但尚未付款，或 Worldline 尚未确认付款。此时只存在购物车。
Payment accepted or Delivered：付款已捕获。状态遵循 Order Status After Payment。付款会以 Worldline 付款 ID 作为交易 ID 记录，备注中会显示金额、付款 ID 以及确认方式（签名 Webhook 或状态检查）。
Awaiting Worldline capture：Worldline 报告付款已授权或捕获已请求，但尚未捕获。目前尚未记录付款。Webhook 确认捕获后，订单会转为已付款状态。如果备注显示付款未捕获，请在 Worldline Merchant Portal 中进行捕获。
Worldline payment on hold：付款与购物车不匹配，例如金额或货币不同（付款开始后购物车被修改），或付款属于另一次付款尝试。备注中会显示已付金额、订单总额和参考号。请检查订单并处理，或退还付款。
Payment error：Worldline 拒绝或取消了一个等待捕获的订单的付款。
Refunded：付款已通过模块全额退款。
如果已取消或已退款订单收到付款，订单不会被重新开启。备注会提示您在 Worldline Merchant Portal 中退款或取消付款，或手动恢复订单。返回的顾客会看到 Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment. 如果已付款的订单收到第二笔付款，订单不会被更改。备注会提示您在 Worldline Merchant Portal 中退还第二笔付款。
Worldline 付款区块
订单页面会显示 Worldline payment 区块，其中包括付款 ID、商户参考号、托管结账页面、尝试状态、已扣金额和已退金额、测试付款的 Test environment 标记、退款记录以及订单的 Payment notes。
退款
在 Worldline payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Worldline。确认提示 Refund this amount through Worldline? This cannot be undone.。支持全额和部分退款。付款必须已被捕获。您需要编辑订单的权限；无需访问模块页面。退款以 Worldline 实际扣款的金额和货币进行，因此在金额或货币不一致后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款始终使用该账户的凭据发送到原始付款所在的环境（测试或正式），因此这些凭据必须已设置。超时后重试的退款不会被执行两次，并且同一订单一次只会执行一笔退款。如果 Worldline 拒绝退款，区块会显示错误，且不会记录任何退款。被接受的退款会连同 Worldline 退款 ID 和状态一起添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会更改状态。
模块不会创建退款凭单。订单页面上 PrestaShop 的标准退款按钮不会通过 Worldline 退回款项。
Worldline 的退款状态变更通过 Webhook 送达，会更新退款记录并添加到备注中。在 Merchant Portal 中进行的退款不会更改订单状态，也不会创建退款凭单。如有需要，请手动更新。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Worldline Gateway 许可证区块是 Modules > Module Manager > VibeFox Worldline Gateway > Configure 页面中位于设置上方的第一个区块。请将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺中移除密钥）。其下方有一行 Product: presta-payment-worldline 以及链接 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Worldline。若仍有付款被发起，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法知道您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会被确认，退款也仍可正常进行。
许可证过期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Worldline：请检查许可证是否有效，Enable/Disable 是否已开启，并且当前模式具有 Merchant ID、API Key ID 和 Secret API Key：测试模式下填写测试字段，正式模式下填写正式字段。缺少这些信息时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许购物车货币、顾客所在国家和顾客所属客户组。
付款已完成，但没有创建订单：Webhook 无法正常工作。在您所用账户（测试或正式）的 Merchant Portal 中，检查端点是否存在，其 URL 是否与 Endpoint URL 中显示的完全一致，且没有重定向。检查该账户的 Webhook secret 是否位于对应字段中（Test Webhook Secret 或 Live Webhook Secret），并且 Webhook 密钥 ID 字段为空或与密钥匹配。顾客付款后返回店铺时，也会创建订单。
Webhook 返回 Webhook secret not configured：两个 Webhook secret 都未设置。请在设置中输入 Webhook secret。Worldline 会重试该 Webhook。
Webhook 返回 Invalid signature：Webhook secret 属于另一个账户或另一个密钥，或者 Webhook 密钥 ID 与发送该 Webhook 的密钥不匹配。请检查测试和正式 secret 是否填反。
Webhook 返回 Missing signature、Empty body 或 Invalid JSON：请求并非以预期格式来自 Worldline，或代理或重定向改变了它。请检查该 URL 是否在没有重定向的情况下响应。
Webhook 返回 Ignored：该 Webhook 来自与该模式设置中不同的 Merchant ID。请检查 Test Merchant ID (PSPID) 或 Live Merchant ID (PSPID)。
Webhook 返回 Retry later：订单正被另一个请求同时确认，或订单无法创建（例如模块已禁用）。Worldline 会重试该 Webhook。请查看 Log 字段了解原因。
Webhook URL 在浏览器中显示 Method not allowed：这是正常的。该 URL 只接受来自 Worldline 的请求。
Test credentials 或 Live credentials 显示错误：请先保存设置，然后检查 Merchant ID、API Key ID 和 Secret API Key 是否来自同一个账户，以及测试值是否位于测试字段、正式值是否位于正式字段。
顾客选择 Worldline 时看到错误：请查看模块页面上的 Log 字段。即使 Logging 关闭，错误也会被记录。要查看请求的完整详细信息，请开启 Logging 并重试。
测试付款不会确认正式付款：测试和正式是分开的。请将 Test Mode 切换为您想使用的模式，并使用该账户的凭据和 Webhook。
付款后订单显示 Worldline payment on hold 或 Awaiting Worldline capture：请阅读 Worldline payment 区块中的备注（参见订单状态）。要么是 Worldline 尚未确认捕获（由 Webhook 完成订单），要么是已付金额或货币与购物车不同。
退款因环境相关的消息而失败：付款是在测试或正式环境中完成的，而该环境的凭据未设置。请输入这些凭据后重试。
开发者：钩子 actionWlgHostedCheckoutData 会在托管结账请求发送前修改它，例如用于限制显示的支付方式。
卸载
进入 Modules > Module Manager，打开 VibeFox Worldline Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便之后重新安装。Worldline 交易和退款，以及订单状态 Awaiting Worldline capture 和 Worldline payment on hold 始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Worldline 是其各自所有者的商标。本模块与 Worldline 没有关联，也未获得 Worldline 的认可。