VibeFox ifthenpay for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。没有它，插件无法启用。
PHP：8.0 或更高版本。
货币：仅支持欧元 (EUR)。当商店或订单货币不是 EUR 时，付款方式会被隐藏。ifthenpay 接受 0.01 至 99,999.99 EUR 的总额。
ifthenpay 账户：请在 ifthenpay.com 注册。您需要所提供付款方式的密钥：Multibanco、MB WAY 或 Credit Card（格式 ABC-123456）。密钥可在 ifthenpay 后台（backoffice.ifthenpay.com）查看，或在您的账户启用该付款方式时由 ifthenpay 发送。ifthenpay 还必须为您的密钥激活回调（见“配置”），并且您的商店必须可以从互联网访问。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_ifthenpay_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。插件会生成其反钓鱼密钥。
3. 打开设置：WooCommerce > Settings > Payments > ifthenpay > Manage，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 选择 Payment Method 并输入其 ifthenpay 密钥。保存设置，使 Callback URL 与所选方式一致。
6. 复制设置中显示的 Anti-phishing Key 和 Callback URL，并请 ifthenpay 为您的密钥激活回调（通过后台或 ifthenpay 支持）。
7. 开启 Enable/Disable。
配置
所有设置都位于一个页面：WooCommerce > Settings > Payments > ifthenpay。如果没有所选方式的密钥，付款方式不会在结账时显示，并且付款方式列表会将其标记为需要处理。保存未提供该密钥的已启用网关时，页面会显示 ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.
Enable/Disable: Enable ifthenpay Payment 用于开启或关闭付款方式。默认：关闭。
Title: 结账时显示的付款方式标题。默认：ifthenpay。
Description: 结账时显示的付款方式说明。默认：Pay via Multibanco, MB WAY or Credit Card。请修改为与您提供的方式相符。
Payment Method: 结账时提供的付款方式。只需要该方式的密钥。
ifthenpay 密钥
密钥（格式 ABC-123456）可在 ifthenpay 后台查看，或在您的账户启用该付款方式时由 ifthenpay 发送。
Multibanco Key: 用于动态参考号的 ifthenpay Multibanco (MB) 密钥。
MB WAY Key: 您的 ifthenpay MB WAY 密钥。
Credit Card Key: 您的 ifthenpay Credit Card 密钥。它还用于验证客户从卡页面返回时的签名。
回调（付款通知）
回调会告知您的商店已完成付款。请为您使用的每个密钥，连同下方的反钓鱼密钥和回调 URL，请 ifthenpay 激活回调。Multibanco 和 MB WAY 订单仅通过回调确认；信用卡付款还会通过卡页面的已签名返回进行确认。
Anti-phishing Key: 由插件生成，显示以供复制。ifthenpay 会在每次回调中将其发回；没有该密钥的回调会被拒绝。
Callback URL: 所选付款方式的回调 URL（含 ifthenpay 占位符），显示以供复制。它以 https://your-site/wc-api/ifthenpay_payment_callback/ 开头，并附带该方式的参数。请完整、准确地复制设置中显示的 URL。
每次回调中的反钓鱼密钥都会与您的密钥进行比对。缺失或错误的密钥会收到 403 响应，订单不会被更改。回调还必须匹配本网关的某个订单：Multibanco 按实体和参考号匹配，MB WAY 按订单及其某个 MB WAY 请求匹配，信用卡按订单及其卡请求匹配。如果没有正常工作的回调，Multibanco 和 MB WAY 订单将永远不会被确认，而信用卡付款只能通过已签名的返回确认。
高级
Test Mode: Enable test/sandbox mode。信用卡和 Multibanco 使用 ifthenpay 沙盒端点；不会扣除真实款项，您应使用 ifthenpay 提供的测试密钥。MB WAY 没有沙盒：请使用 ifthenpay 提供的测试密钥进行测试。结账页面会显示 TEST MODE 标识。默认：关闭。
Order Status After Payment: 确认付款后设置的订单状态，只改变一次状态，并向客户发送一封电子邮件。仅包含可下载虚拟商品的订单始终由 WooCommerce 完成。
Debug Log: Enable logging。API 请求和回调会写入 WooCommerce > Status > Logs，来源为 wcp_ifthenpay_gateway。错误始终会记录。密钥、反钓鱼密钥和电话号码绝不会被记录。默认：关闭。
Delete Data on Uninstall: Remove the plugin settings, the anti-phishing key and the logs when the plugin is deleted (orders are kept)。默认：关闭。
结账
Multibanco。在结账时，客户会看到 You will receive a Multibanco reference to complete the payment. 下单时，插件会为订单总额创建一个动态 Multibanco 参考号。订单变为“等待中”，库存减少，购物车清空。感谢页面以及订单处于等待中时发出的订单电子邮件会显示 Multibanco Payment Details：实体、参考号和金额，并附带 Please use these details to pay at any Multibanco ATM or through your online banking. 如果客户以相同金额再次下单，将复用同一参考号。ifthenpay 发送付款回调后，订单才会被确认。
MB WAY。客户输入 MB WAY phone number（912 345 678、+351 912 345 678，或其他国家的 351#912345678）；账单电话会自动填写。插件会向该手机发送付款请求，订单变为“等待中”，库存减少，购物车清空。感谢页面会显示 A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. 订单的所有请求都会保留，因此之前已在应用中批准的请求仍会被接受。订单通过回调确认。
信用卡。客户会看到 You will be redirected to a secure page to enter your card details. 并被引导至 ifthenpay 卡页面。在付款完成前，订单保持“待付款”，库存在此之前不会减少。付款成功后，客户返回您的商店。只有在 ifthenpay 签名有效、订单密钥、该次尝试的密钥以及订单的卡请求都校验通过时，返回才会被接受，然后订单被标记为已付款。如果无法验证返回，订单不会改变，感谢页面会显示 Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. 卡付款失败会将订单标记为“失败”，取消则让订单保持“待付款”。在这两种情况下，客户都会进入 Pay for order 页面，并显示 The card payment was not completed. You can try again or choose another payment method. 或 The card payment was cancelled. You can try again or choose another payment method.
只有在 ifthenpay 确认付款后，订单才会被标记为已付款，并且金额会与订单总额逐分核对。如果无法发起付款，客户会看到简短提示，例如 The Multibanco reference could not be created. Please try again or choose another payment method.、The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. 或 The payment service is temporarily unavailable. Please try again in a few minutes.
该付款方式适用于经典结账、购物车和结账区块（含 MB WAY 电话字段）以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件同一时间仅提供一种 ifthenpay 付款方式。不支持 Payshop、Cofidis Pay、Apple Pay、Google Pay、PIX 或 Pay-by-Link，不支持订阅或保存的卡，不会自动过期或取消未付款的 Multibanco 参考号，也不会轮询付款状态。
订单
Order statuses
On hold (waiting for payment): 已生成 Multibanco 参考号，或已发送 MB WAY 请求。未付款的参考号不会自动取消；如有需要，请您自行取消此类订单。
Pending payment: 信用卡付款已开始但尚未确认，或已被取消。
Processing or Completed: 付款已确认。状态按照 Order Status After Payment 设置。订单备注显示 Multibanco 实体和参考号、MB WAY 交易或卡请求 ID。
On hold after payment: 收到的金额与订单总额不符，或付款在订单取消后才到达。订单备注会说明原因。请在 ifthenpay 后台核实付款，并手动完成或退款该订单。
Failed: 客户从卡页面返回时出现错误。
对于已付款订单的第二次付款通知，仅会添加一条备注，提醒您在 ifthenpay 后台检查是否存在重复付款。已退款的订单以及付款后取消的订单绝不会被重新打开。
退款
不支持通过 WooCommerce 退款。请在 ifthenpay 后台退款，并在 WooCommerce 中手动记录。已退款（DEVOLVIDO）回调仅添加订单备注。ifthenpay 报告的其他状态也仅添加备注。
许可证密钥
本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > ifthenpay 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，ifthenpay 不会在结账时向客户显示。如果仍然启动了付款，客户会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该付款方式，并标注为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会被确认。
许可证到期后，插件仍可继续运行，但更新和支持需要续订。状态会在后台自动重新检查。
故障排除
ifthenpay 未在结账时显示：请检查许可证是否有效、Enable/Disable 是否开启、所选 Payment Method 的密钥是否已填写、货币是否为 EUR，以及总额是否在 0.01 至 99,999.99 EUR 之间。在 Pay for order 页面，以订单货币为准。
客户已付款，但订单仍为 On hold 或 Pending payment：回调未到达您的商店。请检查 ifthenpay 是否已为您使用的密钥激活回调 URL 和反钓鱼密钥，以及该 URL 是否属于所选方式。站点必须可以从互联网访问，不能是 localhost，也不能位于登录页面之后。请在 WooCommerce > Status > Logs 中查找来源为 wcp_ifthenpay_gateway 的 Callback rejected 记录。
回调返回 403 Forbidden：回调中的反钓鱼密钥缺失，或与设置中的密钥不一致。请将设置中显示的密钥重新发送给 ifthenpay。
回调返回 503 Not configured：反钓鱼密钥尚未生成。请打开一次设置页面；ifthenpay 会重试回调。
回调返回 Order not found：该参考号或请求不属于本网关的订单，例如因为下单后更换了付款方式。
为什么已付款订单被设为 On hold？收到的金额与订单总额不符，或付款在订单取消后才到达。请阅读订单备注，在 ifthenpay 后台核实付款，并手动完成或退款该订单。
MB WAY 请求无法发送：电话号码未绑定 MB WAY，或格式错误。请使用 912 345 678，其他国家的号码请使用 351#912345678。
测试模式与 MB WAY：ifthenpay 没有 MB WAY 沙盒；请使用 ifthenpay 提供的测试密钥。
许可证区块显示错误：请按区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件会继续使用上次已知的状态运行。
卸载
停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态始终会被删除。只有开启了 Delete Data on Uninstall 时，网关设置、反钓鱼密钥和日志才会被删除；否则它们会保留，供以后重新安装时使用。订单及其 ifthenpay 数据（参考号、请求 ID）始终保留。现有订单会保留其付款备注和交易 ID。
ifthenpay 是其各自所有者的商标。本插件与 ifthenpay 无关联，也未获得 ifthenpay 的认可。