VibeFox Worldline for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

Worldline 账户：Worldline Direct（原 Ingenico Direct）商户账户。测试账户和正式账户相互独立，凭据各不相同。每个账户都需要商户 ID（即您的 PSPID）、API Key ID 及其 Secret API Key，以及 Webhook 密钥及其密钥。这些均在 Worldline Merchant Portal 中创建（参见“配置”）。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先在电脑上解压。其中包含 README.txt、OpenCart 3 安装包 wcp_worldline_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_worldline_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_worldline_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接将本安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Worldline Gateway，点击 Install（绿色 + 按钮）。您的管理员用户需要有修改付款扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。在页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见“许可证密钥”）。

4. 输入测试凭据，点击 Save，然后点击 Test credentials。

5. 在测试账户的 Merchant Portal 中添加 Webhook URL，并输入 Webhook 密钥和密钥（参见“配置”）。

6. 开启 Enable/Disable，保存后进行一次测试付款。然后输入正式凭据，在正式账户中重复 Webhook 设置，点击 Live credentials，并关闭 Test Mode。

OpenCart 4

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_worldline_gateway.ocmod.zip。不要重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Worldline Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的第 3 至 6 步输入许可证密钥、凭据和 Webhook。两个版本的设置页面及其字段相同。只有 Webhook URL 不同（参见 Webhook）。

新安装默认关闭付款方式，并开启测试模式。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Worldline Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当当前模式的凭据（商户 ID、API Key ID、Secret API Key）不完整时，页面会发出警告，因为此时付款方式会在结账时隐藏。测试模式开启时，页面会显示 Test mode is on (pre-production environment): no real money is charged. 如果您没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数（允许负数），Total 必须为大于或等于 0 的数字，并且所选的地区和订单状态必须存在。否则不会保存任何内容，页面会指出出错的字段。凭据不完整并不阻止保存。

Worldline（Ingenico）

Enable/Disable：Enable Worldline Gateway 用于开启或关闭付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Worldline。必填，最多 128 个字符。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely via Worldline.

Sort Order：Worldline 在结账付款方式中的位置。可以留空或输入整数。

Geo Zone：仅对所选地区内的付款地址提供 Worldline。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。

Total：订单在商店默认货币下须达到的结账总额，达到后才提供 Worldline。留空则对任何总额都提供 Worldline。

Worldline Direct API

请从测试账户和正式账户的 Worldline Merchant Portal 获取凭据。您的 PSPID 即商户 ID。Developer > Payment API 用于创建 API Key ID 和 Secret API Key，Developer > Webhooks 用于创建 Webhook 密钥和密钥。本部分提供了两个门户以及 Worldline 文档的链接。

Test Mode：同时切换 API 端点和凭据。测试模式使用预生产环境和测试凭据，正式模式使用生产环境和正式凭据。默认：开启。关闭则收取真实付款。测试模式开启期间，顾客在 Confirm Order 步骤会看到 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 密钥。用于验证每个 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 密钥。

已保存的密钥和 Webhook 密钥不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。要删除已保存的值，请勾选字段下方的 Clear the saved value，然后点击 Save。

检查凭据：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 在 OpenCart 3 中形如 https://your-store/index.php?route=extension/payment/wcp_worldline_gateway/webhook，在 OpenCart 4 中则形如 https://your-store/index.php?route=extension/wcp_worldline_gateway/payment/wcp_worldline_gateway.webhook，由您 OpenCart 安装的商店地址生成。请完全按照设置中显示的内容复制该 URL：它必须在不重定向的情况下作出响应，并且可以从互联网访问。然后在 Test Webhook Key ID 和 Test Webhook Secret 中输入 Webhook 密钥 ID 和密钥。在正式账户中，使用正式字段进行同样的设置。

扩展会自动响应 Worldline 的端点验证请求。它处理付款事件（付款状态变化）和退款事件（退款状态变化）。其他事件会被接受但忽略。没有有效签名的 Webhook 会被拒绝。事件必须使用付款所在账户的密钥签名，因此测试 Webhook 绝不会确认正式付款。如果 Webhook 来自与签名密钥所属账户不同的商户 ID，同样会被忽略。如果没有 Webhook，只有在顾客付款后返回商店时，订单才会被确认。

付款页面和订单

Payment page template：在 Merchant Portal 中上传的托管结账模板（变体）的可选名称，例如 SimplifiedCustomPaymentPage。留空则使用 Worldline 的默认页面。

Order Status After Payment：已捕获的付款设置为哪种状态。付款始终以直接销售（授权并捕获）的方式请求。

OpenCart 在 Confirm Order 步骤创建订单时不带状态（即缺失订单）。只有 Worldline 确认付款后，订单才会获得状态。下方每个字段都会列出您的 OpenCart 订单状态。

Paid Order Status：以 Payment accepted (processing) 捕获付款后的状态。默认：Processing。

Complete Order Status：以 Delivered (completed) 捕获付款后的状态。默认：Complete。

Awaiting Capture Status：付款已授权或已请求捕获；捕获 Webhook 会将订单标记为已付款。默认：Pending。

On Hold (Review) Status：已付金额或货币与订单不符。备注会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Payment Error Status：Worldline 拒绝或取消了一个等待捕获的订单的付款。默认：Failed。

Refunded Status：付款已从订单页面全额退款。默认：Refunded。

高级

Logging：将所有 API 请求和 Webhook 写入 OpenCart 日志文件夹（storage/logs）中的 wlg_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会移动到 wlg_debug.old.log.php。即使此选项关闭，错误和警告也始终会记录。密钥、银行卡信息和个人数据都会被隐去。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Delete Data：开启后，卸载扩展时会删除网关设置和日志。Worldline 的交易和退款始终保留，因为现有订单需要它们来办理退款。默认：关闭。

Import / Export

Export：Download JSON 会将设置保存为 JSON 文件。密钥和 Webhook 密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的密钥会被保留。

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 Worldline）。在 Confirm Order 步骤，顾客会看到您的描述。OpenCart 在此步骤创建订单，仍然没有状态。顾客点击 Confirm Order 后，扩展会以订单货币为订单总额创建一个 Worldline 托管结账页面，并将顾客带到 Worldline 付款页面。顾客在该页面使用银行卡、电子钱包或您 Worldline 账户中启用的其他付款方式付款。账单姓名、地址、电子邮件和电话会传递给 Worldline，并且在 Worldline 支持的情况下，付款页面会以顾客的语言打开。每次付款尝试都会获得由订单号和随机部分组成的独立参考号。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并在结账页面底部点击 Confirm Order。

付款后，顾客返回您的商店。扩展会将返回请求与已保存的尝试进行核对，并在服务器端从 Worldline 读取付款状态。只有在 Worldline 通过此状态检查或经签名的 Webhook 确认后，订单才会被标记为已付款。之后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 订单成功页面，并显示 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 一到达就会设置订单状态。

在 OpenCart 4 中，这些消息会显示在结账页面上方。

每次显示 Confirm Order 步骤时，OpenCart 3 都会创建一个新订单；OpenCart 4 则会为结账保留一个订单并更新它，因此取消或拒绝后，顾客会在新的 Worldline 付款页面上支付同一订单。在新的付款之前，扩展会检查购物车：如果同一购物车的另一笔订单已付款，或上一次尝试在此期间已付款，顾客会直接进入成功页面，而不会被重复扣款。如果同一订单的上一个付款页面仍然打开，金额和模式相同，并且创建时间不到 30 分钟，顾客会被送回该页面。

在 OpenCart 4 中，如果订单在授权后被拒绝或取消，则下一次 Confirm Order 会将顾客送回结账页面并显示有关被拒付款的消息，而不是成功页面。如果商店已关闭该订单（例如取消或退款），消息为 Your previous order was closed by the shop (cancelled / refunded). Please confirm the order again to pay with a new order. 两种情况下，下一次 Confirm Order 都会支付新订单。如果结账中的订单已付款，但购物车此后有变化（包括新数量），顾客会被送回结账页面，新购物车将以新订单付款。

如果 Worldline 无法启动付款，顾客会停留在 Confirm Order 步骤，按钮上方显示 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 和顾客的返回也能正常工作：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展为其添加了启动动作。

扩展以直接销售的方式在 Worldline 页面接受一次性付款。它不支持保存银行卡或令牌化，不支持订阅，不支持嵌入式银行卡表单，不支持在 OpenCart 中进行仅授权并随后捕获或取消的模式，不支持附加费，也不支持自动注册 Webhook。

订单与退款

订单状态

无状态（缺失订单）：顾客已被带到 Worldline 但未付款，或 Worldline 尚未确认付款。在 Sales > Orders 中，此类订单仅在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Paid Order Status 或 Complete Order Status（默认 Processing 或 Complete）：付款已捕获。状态遵循 Order Status After Payment。备注会显示金额、Worldline 付款 ID 以及确认方式（经签名的 Webhook 或状态检查）。

Awaiting Capture Status（默认 Pending）：Worldline 报告付款已授权或捕获已请求，但尚未捕获。当 Webhook 确认捕获后，订单会转为已付款状态。如果备注显示付款未捕获，请在 Worldline Merchant Portal 中捕获。

On Hold (Review) Status（默认 Pending）：付款与订单不符，例如金额或货币不一致，或付款属于另一笔尝试。备注会显示已付金额、订单总额和参考号。请检查订单并处理，或对付款进行退款。

Payment Error Status（默认 Failed）：Worldline 拒绝或取消了一个等待捕获的订单的付款。

Refunded Status（默认 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 中对第二笔付款进行退款。

备注是订单 History 中顾客看不到的条目。它们以 Worldline 一词开头。

VibeFox Worldline Gateway 选项卡

在 Sales > Orders 中打开一个通过 Worldline 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox Worldline Gateway 选项卡会显示 Worldline payment 区块：Payment ID、Merchant reference、Hosted checkout、尝试的 Status、Amount charged / refunded、测试付款的 Test environment 标签、退款表单、退款记录以及订单的 Payment notes。该选项卡会显示给有权访问该扩展的用户。

退款

在 VibeFox Worldline Gateway 选项卡中输入金额（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Worldline。确认提示 Refund this amount through Worldline? This cannot be undone. 支持全额和部分退款。付款必须已经捕获。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。退款金额和货币与 Worldline 实际扣款一致，因此在金额或货币不符之后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款总是通过该账户的凭据发送到原始付款所在的环境（测试或正式），因此这些凭据必须已设置。超时后重试的退款不会被执行两次，并且同一订单一次只会执行一笔退款。如果 Worldline 拒绝退款，选项卡会显示错误，并且不会记录退款。被接受的退款会连同 Worldline 退款 ID 和状态一起添加到退款记录和备注中。全额退款会将订单设置为 Refunded Status，不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。

Sales > Returns 中的商品退货不会通过 Worldline 退还款项。

Worldline 的退款状态变更通过 Webhook 送达，会更新退款记录并添加到备注中。在 Merchant Portal 中进行的退款不会改变订单状态；如有需要，请手动更新。

许可证密钥

扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Worldline Gateway 许可证区块是 Extensions > Extensions > Payments > VibeFox Worldline Gateway > Edit 页面中位于设置上方的第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: opencart-payment-worldline 一行和 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。商店地址变更后，或在 vibefox.net 账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额，请在 vibefox.net 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 Worldline。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 以同一浏览器登录后台的管理员用户，仍会在商店中看到该付款方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置并测试扩展。在 OpenCart 4 中此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台的 Dashboard 会出现提醒。点击 × 可关闭，并在 7 天内隐藏。现有订单不受影响：已经开始的付款仍会被确认，退款也仍然可以进行。

许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 Worldline：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否具有商户 ID、API Key ID 和 Secret API Key：测试模式下使用测试字段，正式模式下使用正式字段。缺少时，设置页面会显示警告。另请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Webhook 未正常工作。在您所用账户（测试或正式）的 Merchant Portal 中，检查端点是否存在，以及其 URL 是否与 Endpoint URL 中显示的完全一致且没有重定向。检查该账户的 Webhook 密钥是否位于对应字段（Test Webhook Secret 或 Live Webhook Secret）中，并且 Webhook 密钥 ID 字段为空或与密钥匹配。顾客付款后返回商店时，订单也会获得状态。

Webhook answers Webhook secret not configured：两个 Webhook 密钥都未设置。请在设置中输入 Webhook 密钥。Worldline 会重试该 Webhook。

Webhook answers Invalid signature：Webhook 密钥属于其他账户或其他密钥，或者 Webhook 密钥 ID 与发送该 Webhook 的密钥不匹配。请检查测试和正式密钥是否被互换。

Webhook answers Missing signature、Empty body 或 Invalid JSON：请求不是以预期格式来自 Worldline，或者代理或重定向修改了它。请检查 URL 是否在没有重定向的情况下作出响应。

Webhook answers Ignored：该 Webhook 来自与该模式设置中不同的商户 ID。请检查 Test Merchant ID (PSPID) 或 Live Merchant ID (PSPID)。

Webhook answers Retry later：订单在同一时刻正被另一个请求确认，或者无法设置订单状态。Worldline 会重试该 Webhook。请查看 Log 字段了解原因。

Webhook URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 Worldline 的请求。

Test credentials 或 Live credentials 显示错误：请先保存设置，然后检查商户 ID、API Key ID 和 Secret API Key 是否来自同一账户，以及测试值是否位于测试字段中、正式值是否位于正式字段中。

顾客在 Confirm Order 后看到错误：请查看扩展页面上的 Log 字段。即使 Logging 关闭，错误也会被记录。如需完整的请求详情，请开启 Logging 后重试。

测试付款不会确认正式付款：测试和正式是分开的。将 Test Mode 切换到您想使用的模式，并使用该账户的凭据和 Webhook。

付款后订单处于审核或等待捕获状态：请阅读 VibeFox Worldline Gateway 选项卡中的备注（参见订单状态）。要么 Worldline 尚未确认捕获（Webhook 会完成订单），要么已付金额或货币与订单不符。

选项卡中没有退款表单：选项卡会说明原因：没有已捕获的 Worldline 付款、付款已全额退款、您的用户组没有修改扩展的权限，或付款所在环境的凭据未设置。

退款因环境相关消息失败：付款是在测试或正式环境中进行的，而该环境的凭据未设置。请输入这些凭据后重试。

面向开发者：在创建托管结账页面之前，扩展会携带请求数据和订单触发 OpenCart 事件 wlg_hosted_checkout_data，例如用于限制显示的付款方式。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Worldline Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Payment page and orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。该扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件以及在维护模式下放行 Webhook 和顾客返回的启动动作）。如果 Delete Data 已开启，其他网关设置（标题、描述、测试模式、凭据、Webhook 密钥、页面模板、日志记录）和日志都会被删除。如果已关闭，它们会被保留，以便日后重新安装时使用。Worldline 的交易和退款始终会被保留，因此之前付款的订单在重新安装后仍可办理退款。现有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Worldline Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

Worldline 是其各自所有者的商标。本扩展与 Worldline 没有关联，也未获得 Worldline 的认可。