VibeFox ifthenpay for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。在较旧的 PHP 版本上，模块会拒绝安装。
货币：仅支持欧元 (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. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure，或稍后在模块列表中找到 VibeFox ifthenpay Gateway 并点击 Configure。模块会在安装时生成其反钓鱼密钥。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 选择 Payment Method，输入其 ifthenpay 密钥，然后点击 Save，使 Callback URL 与所选方式相符。
5. 复制设置中显示的 Anti-phishing Key 和 Callback URL，然后请 ifthenpay 为您的密钥激活回调（通过后台或 ifthenpay 支持）。
6. 开启 Enable/Disable，然后点击 Save。
安装时，模块会创建两个订单状态：Awaiting ifthenpay payment 和 ifthenpay payment on hold。PrestaShop 会为所有货币、国家和客户组提供一个新的付款模块。您可以在 Payment > Preferences 中加以限制；必须保留 EUR 的允许状态。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox ifthenpay Gateway > Configure。每个带有 Save 按钮的部分都会保存整个页面。如果没有所选付款方式的密钥，结账时不会显示该付款方式。在没有该密钥的情况下启用网关时，页面会显示 ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.
ifthenpay
Enable/Disable：Enable ifthenpay Payment 用于启用或禁用该付款方式。默认：off。
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 密钥。它还用于验证客户从卡页面返回时的签名。
已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Clear saved keys：勾选某个密钥，然后点击 Save 将其删除。字段为空时将保留已保存的值。
Callback（付款通知）
回调会告知您的商店已完成付款。请为您使用的每个密钥，请 ifthenpay 使用下方的反钓鱼密钥和回调 URL 激活回调。Multibanco 和 MB WAY 订单只由回调确认；卡付款还会由卡页面的已签名返回进行确认。
Anti-phishing Key：由模块生成，显示以便复制。ifthenpay 会在每次回调中将其发回；不包含该密钥的回调会被拒绝。
Callback URL：所选付款方式的回调 URL，包含 ifthenpay 占位符，显示以便复制。启用友好 URL 时，它的开头类似于 https://your-shop/module/wcp_ifthenpay_gateway/callback，可能包含语言代码，例如 /en/，之后是该付款方式的参数。请完整复制设置中显示的 URL。
每次回调中的反钓鱼密钥都会与您的密钥进行比对。缺少或错误的密钥会收到 403 响应，订单不会被更改。回调还必须与本模块的某笔付款相符：Multibanco 通过实体编号和参考号，MB WAY 通过购物车及其某个 MB WAY 请求，Credit Card 通过购物车及其某个卡请求。没有正常工作的回调，Multibanco 和 MB WAY 订单将永远无法确认，卡付款则只能通过已签名的返回确认。回调在商店处于维护模式时仍然有效，并且不受商店国家限制的阻挡。
高级
Test Mode：Credit Card 和 Multibanco 使用 ifthenpay 沙盒端点；不会扣除真实资金，您使用 ifthenpay 提供的测试密钥。MB WAY 没有沙盒：请使用 ifthenpay 提供的测试密钥进行测试。结账时会显示 TEST MODE 标识。默认：off。
Order Status After Payment：付款确认后设置的订单状态，只进行一次状态变更。
Debug Log：API 请求和回调会写入模块文件夹中的 logs/ifthenpay_p_debug.log.php。该文件无法通过网页打开。错误始终会被记录。密钥、反钓鱼密钥和完整电话号码永远不会被记录。默认：off。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete Data on Uninstall：开启时，卸载模块会删除模块设置、反钓鱼密钥和日志。订单和 ifthenpay 付款记录始终保留。默认：off。
结账
Multibanco。结账时，客户会看到 You will receive a Multibanco reference to complete the payment. 客户确认后，模块会为购物车总额生成动态 Multibanco 参考号，并以 Awaiting ifthenpay payment 状态创建订单。订单确认页面会显示 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）；账单地址中的电话会自动填入。模块会向该电话发送付款请求，订单以 Awaiting ifthenpay payment 状态创建。订单确认页面显示 A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. 当 ifthenpay 发送回调时，订单即标记为已付款。系统仅存储经过遮蔽的电话号码。
信用卡。客户会看到 You will be redirected to a secure page to enter your card details. 并被转到 ifthenpay 卡页面。此时尚未创建订单，购物车会被保留。付款成功后，客户会返回您的商店。只有在 ifthenpay 签名有效、购物车的安全密钥、本次尝试的秘密值以及购物车的卡请求全部匹配时，返回才会被接受；随后订单以已付款状态创建，客户会看到标准的订单确认页面。如果无法验证返回，则不会有任何变化，并且 Payment confirmation 页面会显示 Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. 以及 Check again 按钮；回调一到达，订单就会被创建。如果卡付款失败或被取消，客户会返回结账页面，并看到 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. 技术原因会写入日志。
模块每次只提供一种 ifthenpay 付款方式。不支持 Payshop、Cofidis Pay、Apple Pay、Google Pay、PIX 或 Pay-by-Link，不支持订阅或保存的卡，不会自动过期或取消未付款的 Multibanco 参考号，也不会轮询付款状态。
订单
订单状态
No order yet：卡付款已开始但尚未确认，或已失败或被取消。此时只存在购物车。
Awaiting ifthenpay payment：已生成 Multibanco 参考号或已发送 MB WAY 请求。订单创建时，PrestaShop 会减少库存。未付款的参考号和被拒绝的 MB WAY 请求不会自动取消订单；如有需要，请您自行取消这些订单。
Payment accepted or Delivered：付款已确认。状态遵循 Order Status After Payment。付款会以 Multibanco 参考号、MB WAY 请求 ID 或卡请求 ID 作为交易 ID 记录，备注会显示确认方式。
ifthenpay payment on hold：收到的金额与订单总额不一致（例如，卡付款开始后购物车被修改），或付款是在订单被取消之后到达的。备注会说明情况，并且不会要求客户再次付款。请在 ifthenpay 后台核对付款，然后手动完成或退款该订单。此后该订单若收到正确的付款，状态也不会改变。
对于已付款的订单，第二笔付款只会添加一条备注，提醒您在 ifthenpay 后台检查是否为重复付款。已退款的订单以及付款后被取消的订单，永远不会被重新打开。
ifthenpay 付款区块
订单页面会显示 ifthenpay payment 区块，其中包含该订单的付款尝试（日期、方式、测试付款的 Sandbox 标识、金额、Multibanco 实体编号和参考号或经过遮蔽的 MB WAY 电话、ifthenpay 请求 ID 和状态）、订单处于 ifthenpay payment on hold 时显示的 Manual review 警告，以及该订单的 ifthenpay notes。
退款
不支持通过 PrestaShop 退款。请在 ifthenpay 后台退还付款，并在 PrestaShop 中手动记录。已退款（DEVOLVIDO）的回调只会添加备注。ifthenpay 报告的其他状态也只会添加备注。
许可证密钥
模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox ifthenpay Gateway 是 Modules > Module Manager > VibeFox ifthenpay Gateway > Configure 页面顶部的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以遮蔽形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除该密钥）。其下方有一行 Product: presta-payment-ifthenpay，以及 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 账户中释放该名额。
没有有效密钥时，结账时不会向客户显示 ifthenpay。如果仍然发起了付款，客户会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试它。Modules > Module Manager 的 Alerts 标签页中会出现提醒。现有订单不受影响：已经开始的付款仍会被确认。
许可证到期后，模块仍会继续运行，但更新和支持需要续订。在您使用后台时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
ifthenpay 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启、所选 Payment Method 的密钥是否已填写、购物车货币是否为 EUR，以及总额是否在 0.01 至 99,999.99 EUR 之间。在 Payment > Preferences 中检查模块是否允许用于 EUR、客户所在国家和客户组。
客户已付款，但订单仍处于 Awaiting ifthenpay payment 状态或未创建订单：回调未能到达您的商店。请检查 ifthenpay 是否已为您使用的密钥激活回调 URL 和反钓鱼密钥，以及该 URL 是否属于所选付款方式。商店必须能够从互联网访问，不能是 localhost，也不能位于登录页面之后。请在模块页面的 Log 字段中查找 Callback rejected 行。
回调返回 403 Forbidden：回调中的反钓鱼密钥缺失，或与设置中的不一致。请将设置中显示的密钥重新发送给 ifthenpay。
回调返回 503 Not configured：反钓鱼密钥尚未生成。请打开一次模块设置；ifthenpay 会重试回调。
回调返回 503 Busy：该时刻同一购物车正被另一个请求处理。ifthenpay 会重试回调。
回调返回 Order not found：该参考号或请求不属于本模块的付款，或者该购物车使用了其他付款方式下单。
为什么已付款的订单被置为等待？收到的金额与订单总额不一致，或付款是在订单被取消之后到达的。请阅读 ifthenpay payment 区块中的备注，在 ifthenpay 后台核对付款，然后手动完成或退款该订单。
无法发送 MB WAY 请求：电话号码未绑定 MB WAY，或格式错误。请使用 912 345 678；其他国家的号码请使用 351#912345678。
测试模式与 MB WAY：ifthenpay 没有 MB WAY 沙盒；请使用 ifthenpay 提供的测试密钥。
卸载
进入 Modules > Module Manager，打开 VibeFox ifthenpay Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，模块设置、反钓鱼密钥和日志都会被删除；重新安装后会生成新的反钓鱼密钥，并且必须再次发送给 ifthenpay。如果该选项关闭，所有设置都会保留，以便日后重新安装。ifthenpay 付款记录（参考号和请求 ID）以及 Awaiting ifthenpay payment 和 ifthenpay payment on hold 订单状态始终保留，因此对于之前已生成的参考号，回调在重新安装后仍能找到对应订单。现有订单会保留其付款备注和交易 ID。
ifthenpay 是其各自所有者的商标。本模块与 ifthenpay 无关联，也未获得 ifthenpay 的认可或背书。