VibeFox Worldline for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法激活。
PHP：8.0 或更高版本。
Worldline 账户：一个 Worldline Direct（原 Ingenico Direct）商户账户。测试和正式账户相互独立，凭据各不相同。每个账户都需要商户 ID（您的 PSPID）、一个 API Key ID 及其 Secret API Key，以及一个 Webhook 密钥及其 Secret。所有这些都在 Worldline Merchant Portal 中创建（参见「Configuration」）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_worldline_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Worldline (Ingenico) > Manage，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入测试凭据，保存设置，然后点击 Test credentials。
6. 在测试账户的 Merchant Portal 中添加 Webhook URL，并输入 Webhook 密钥和 Secret（参见「Configuration」）。
7. 开启 Enable/Disable 并进行一次测试付款。然后输入正式凭据，在正式账户中重复 Webhook 设置，点击 Live credentials，并取消勾选 Test Mode。
Configuration
所有设置都在同一页面：WooCommerce > Settings > Payments > Worldline (Ingenico)。在付款方式列表中，在当前模式具备商户 ID、API Key ID 和 Secret API Key 之前，Worldline 会被标记为需要设置。在设置页面上，未使用模式的凭据字段会呈灰色显示。
General
Enable/Disable：Enable Worldline Gateway 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。默认：Worldline。
Description：结账时显示在付款方式下方的文字。默认：Pay securely via Worldline.
Worldline Direct API
分别在测试账户和正式账户的 Worldline Merchant Portal 中获取凭据。您的 PSPID 即为商户 ID。Developer > Payment API 用于创建 API Key ID 和 Secret API Key，Developer > Webhooks 用于创建 Webhook 密钥和 Secret。本节提供两个门户及 Worldline 文档的链接。
Test Mode：Enable test mode (pre-production environment, no real money) 会同时切换 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。
检查凭据
Test credentials 和 Live credentials 按钮会通过一次对 Worldline 的测试调用，检查各账户已保存的凭据。请先保存更改。结果会显示在按钮旁边，例如 Test credentials: connection successful.、API credentials are not configured. 或 Worldline 返回的错误信息。
Webhooks
即使顾客没有返回店铺（例如关闭了浏览器，或付款稍后才被确认），Webhook 也会将付款信息告知您的店铺。在测试账户的 Merchant Portal 中打开 Developer > Webhooks，并添加本设置部分显示的端点 URL。它的格式类似 https://your-site/wc-api/wlg_worldline_webhook/。请完全按照设置中显示的内容复制 URL：它必须无需重定向即可响应，因此请检查语言前缀，以及是否存在强制 www 或 https 的重定向。然后在 Test Webhook Key ID 和 Test Webhook Secret 中输入 Webhook 密钥 ID 和 Secret。在正式账户中，使用正式字段进行相同设置。
插件会自动响应 Worldline 的端点验证请求。它处理付款事件（付款状态变化）和退款事件（退款状态变化）。其他事件会被接受但忽略。没有有效签名的 Webhook 会被拒绝。如果 Webhook 来自与签署该 Webhook 的 Secret 所属账户不同的商户 ID，也会被忽略。没有 Webhook 时，只有在顾客付款后返回店铺，订单才会被确认。
付款页面与订单
Payment page template：在 Merchant Portal 中上传的托管支付页面模板（变体）的可选名称，例如 SimplifiedCustomPaymentPage。留空则使用 Worldline 默认支付页面。
Order Status After Payment：Worldline 确认已扣款后订单设置的状态。该状态会立即设置，无需第二次状态更改。付款始终以直接销售方式（授权和扣款）发起。
Logging：Enable debug logging 会将所有 API 请求和 Webhook 写入 WooCommerce > Status > Logs，来源为 wcp_worldline_gateway。即使此选项关闭，错误和警告也始终会被记录。密钥、银行卡数据和个人数据都会被脱敏。默认：关闭。
Delete Data：Delete the plugin settings and logs when the plugin is deleted。停用插件绝不会删除任何内容。订单中保存的付款数据会保留，因为退款需要这些数据。默认：关闭。
从 1.0 版本更新时，旧的单组凭据会根据店铺当时使用的模式，迁移到测试或正式字段中。
结账
顾客选择付款方式（默认为 Worldline）并下单。插件会按订单金额以订单货币创建 Worldline 托管支付页面，并将顾客引导至 Worldline 付款页面。顾客在那里使用银行卡、电子钱包或您 Worldline 账户中已启用的其他付款方式付款。账单姓名、地址、电子邮件和电话会传递给 Worldline；如果 Worldline 支持，付款页面会以您店铺的语言打开。每次付款尝试都会获得自己的参考号，由订单 ID 和一段随机字符组成。
付款后，顾客返回您的店铺。插件会根据已保存的付款尝试核对返回信息，并在服务器端从 Worldline 读取付款状态。只有在 Worldline 确认后，订单才会被标记为已付款：通过此状态检查，或通过已签名的 Webhook。随后，顾客会看到订单已接收页面。
如果付款未完成，顾客会被带到 Pay for order 页面，并显示相应消息：
顾客可以从 Pay for order 页面为未付款的订单重新付款。如果之前的尝试在此期间已付款，顾客会直接进入订单已接收页面，不会被重复扣款。如果之前的付款页面仍为相同金额和模式保持打开，且创建于 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.
该付款方式适用于经典结账、结账区块以及 Pay for order 页面，并兼容 WooCommerce 高性能订单存储（HPOS）。
插件以直接销售方式在 Worldline 页面接受一次性付款。它不支持保存银行卡或令牌化、订阅、嵌入式银行卡表单、在 WooCommerce 中进行仅授权并随后扣款或取消的模式、附加费或自动注册 Webhook。
订单与退款
Order statuses
Pending payment：顾客已被送往 Worldline 但尚未付款，或 Worldline 尚未确认付款。备注中会显示托管支付页面 ID、参考号以及模式（测试或正式）。
Processing or Completed：付款已扣款。状态遵循 Order Status After Payment 的设置。订单备注会显示金额、Worldline 付款 ID，以及确认方式（已签名的 Webhook 或状态检查）。订单的交易 ID 即为 Worldline 付款 ID。
On hold, waiting for capture：Worldline 将付款报告为已授权，或扣款已请求但尚未完成。订单备注会对此进行说明。当 Webhook 确认扣款后，订单会自动标记为已付款。如果备注显示付款未扣款，请在 Worldline Merchant Portal 中完成扣款。
On hold, held for manual review：付款与订单不匹配，例如金额或货币不同（订单在付款开始后被修改），或付款属于另一笔尝试。备注会显示已付金额、订单总额和参考号。请检查订单并完成发货，或退还该笔付款。
Failed：Worldline 拒绝或取消了最新一次尝试的付款，或顾客不符合所选付款方式的条件。
Cancelled：订单由您取消，或因 WooCommerce 库存保留超时而取消。如果付款到达已取消或已退款的订单，订单不会被重新开启。备注会提示您在 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 中退还第二笔付款。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Worldline (Ingenico)。支持全额和部分退款。付款必须已扣款。退款始终会使用该账户的凭据发送到原始付款所在的环境（测试或正式），因此必须已设置这些凭据。超时后重试的退款不会被执行两次。如果 Worldline 拒绝退款，WooCommerce 会显示错误，且不会记录任何退款。被接受的退款会以 Worldline 退款 ID 和状态添加到订单备注中。
Worldline 的退款状态变更通过 Webhook 送达，并添加到订单备注中。在 Merchant Portal 中进行的退款不会自动记录为 WooCommerce 退款。如有需要，请在 WooCommerce 中创建手动退款，且不要使用 Refund via Worldline (Ingenico)。
许可证密钥
插件需要使用在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Worldline (Ingenico) 的顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将密钥从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 Worldline。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款功能也照常工作。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 Worldline：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式是否具备商户 ID、API Key ID 和 Secret API Key：测试模式下填写测试字段，正式模式下填写正式字段。如果缺少这些信息，付款列表会将该付款方式标记为需要设置。
付款已成功，但订单仍为 Pending payment：Webhook 无法工作。请在您所用账户（测试或正式）的 Merchant Portal 中检查端点是否存在，且其 URL 与设置中显示的完全一致，并且没有重定向。检查该账户的 Webhook Secret 是否填写在对应字段中（Test Webhook Secret 或 Live Webhook Secret），以及 Webhook Key ID 是否为空或与密钥一致。顾客付款后返回店铺时，订单也会被确认。
Webhook 返回 Webhook secret not configured：未设置任何 Webhook Secret。请在设置中输入 Webhook Secret。Worldline 会重试 Webhook。
Webhook 返回 Invalid signature：Webhook Secret 属于其他账户或其他密钥，或者 Webhook Key ID 与发送该 Webhook 的密钥不匹配。
Webhook 返回 Missing signature、Empty body 或 Invalid JSON：请求不是以预期格式来自 Worldline，或者被代理或重定向修改了。请检查 URL 是否无需重定向即可响应。
Webhook 返回 Ignored：该 Webhook 来自与该模式设置中不同的商户 ID。请检查 Test Merchant ID (PSPID) 或 Live Merchant ID (PSPID)。
Webhook 返回 Retry later：订单在同一时刻正被另一请求更新。Worldline 会重试 Webhook。
Test credentials 或 Live credentials 显示错误：请先保存设置，然后检查 Merchant ID、API Key ID 和 Secret API Key 是否来自同一账户，并确认测试值填写在测试字段中、正式值填写在正式字段中。
顾客下单时看到错误：请打开订单备注，或打开 WooCommerce > Status > Logs，来源 wcp_worldline_gateway。即使调试日志关闭，错误也会被记录。如需查看请求的完整详情，请开启 Logging 后重试。
测试付款无法确认正式订单：测试与正式相互独立。使用测试 Secret 签名的 Webhook 绝不会确认正式付款尝试，反之亦然。请将 Test Mode 切换到您需要的模式，并使用该账户的凭据和 Webhook。
付款后订单处于 On hold：请阅读订单备注。要么 Worldline 尚未确认扣款（Webhook 会完成订单），要么已付金额或货币与订单不符。
退款因环境相关消息而失败：付款是在测试或正式环境中完成的，而该环境的凭据尚未设置。请填写这些凭据后重试。
开发者：过滤器 wlg_hosted_checkout_data 可修改托管支付页面请求，例如限制显示的付款方式；wlg_gateway_icon 可修改付款方式图标。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件会继续使用最后已知的状态运行。
卸载
停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置和日志仅在 Delete Data 开启时才会被删除；否则会保留，以便日后重新安装。订单中保存的 Worldline 付款数据始终会保留，因为退款需要这些数据。现有订单会保留其付款备注和交易 ID。
Worldline 是其各自所有者的商标。本插件与 Worldline 无关联，也未获得 Worldline 的认可。