VibeFox ifthenpay for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：仅支持欧元（EUR）。您的店铺必须启用 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 还必须为您的密钥启用回调（callback）（参见配置），并且您的店铺必须可以从互联网访问。

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

安装

下载包是一个 zip 文件，内含适用于两个 OpenCart 版本的安装包。请解压到您的计算机上。其中包含 README.txt、OpenCart 3 安装包 wcp_ifthenpay_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_ifthenpay_gateway.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

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

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox ifthenpay Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。该扩展会在安装时生成其防钓鱼密钥（anti-phishing key）。

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

4. 选择 Payment Method，输入其 ifthenpay 密钥，然后点击 Save，使 Callback URL 与所选付款方式相符。

5. 从 Callback 部分复制 Anti-phishing Key 和 Callback URL，并请 ifthenpay 为您的密钥启用回调（可在后台或通过 ifthenpay 支持进行）。

6. 开启 Enable/Disable，然后点击 Save。

OpenCart 4

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

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

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

4. 输入许可证密钥、付款方式及其密钥，并按照 OpenCart 3 的第 3 至 6 步启用回调。两个版本的设置页面及其字段相同。只有回调 URL 不同（参见 Callback）。

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

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox ifthenpay Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。如果没有所选付款方式的密钥，结账时将不会显示该付款方式。在没有该密钥的情况下启用网关时，页面会显示 ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout. 如果您没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，付款方式必须有效，标题最多 128 个字符，Sort Order 必须是整数，Total 必须是大于或等于 0 的数字，地区（geo zone）和订单状态必须存在；否则不会保存任何内容。

ifthenpay

Enable/Disable: Enable ifthenpay Payment 用于开启或关闭该付款方式。默认：关闭。

Title: 结账时显示的付款方式标题。它也是订单中保存的付款方式名称。默认：ifthenpay。如果留空，结账时将显示 ifthenpay。

Description: 顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay via Multibanco, MB WAY or Credit Card。请将其修改为与您提供的付款方式相符的内容。

Payment Method: 结账时提供的付款方式。只需填写该付款方式的密钥。

Sort Order: ifthenpay 在结账付款方式中的排列位置。留空或输入整数。

Geo Zone: 仅向所选地区内的账单地址提供 ifthenpay。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。

Total: 订单必须达到的结账金额（以商店默认货币计），达到后才会提供 ifthenpay。留空则对任何金额都提供 ifthenpay。只有当顾客使用 EUR 付款、金额在 0.01 至 99,999.99 EUR 之间时，才会提供 ifthenpay 本身。

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 the saved key on save，然后点击 Save。

Callback

回调会告知您的店铺已完成付款。请为您使用的每个密钥，向 ifthenpay 申请启用回调，并提供本部分中的防钓鱼密钥和回调 URL。Multibanco 和 MB WAY 订单仅通过回调确认；银行卡付款还会通过银行卡页面返回的签名结果确认。

Anti-phishing Key: 由扩展生成，并显示以便复制。ifthenpay 会在每次回调中将其发回；不包含该密钥的回调会被拒绝。

Callback URL: 所选付款方式的回调 URL（带有 ifthenpay 占位符），显示以便复制。在 OpenCart 3 中它以 https://your-store/index.php?route=extension/payment/wcp_ifthenpay_gateway/callback 开头，在 OpenCart 4 中以 https://your-store/index.php?route=extension/wcp_ifthenpay_gateway/payment/wcp_ifthenpay_gateway.callback 开头，由您的 OpenCart 安装的店铺前台地址生成，并附加该付款方式的参数。请完整复制 URL，并与设置中显示的内容完全一致。如果您更改了 Payment Method，请先保存，然后复制新的 URL。

每次回调中的防钓鱼密钥都会与您的密钥进行比对。缺少或错误的密钥会返回 403，订单不会被更改。回调还必须与本扩展的某笔付款相匹配：Multibanco 按实体和参考号匹配，MB WAY 按订单及其某个 MB WAY 请求匹配，Credit Card 按订单及其某个银行卡请求匹配。如果回调无法正常工作，Multibanco 和 MB WAY 订单将永远不会被确认，银行卡付款只能通过签名返回来确认。即使店铺处于维护模式，回调仍然有效：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动操作，放行回调以及顾客从银行卡页面的返回请求。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。对于 Multibanco 和 MB WAY，只要 ifthenpay 生成了参考号或 MB WAY 请求，订单就会获得等待状态；对于 Credit Card，订单只有在收到回调或签名返回后才会获得状态。只有当金额与订单总额精确到分相符时，订单才会被标记为已付款。下面每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment: 付款确认后设置的状态。默认：处理中。

Awaiting payment status: 已生成 Multibanco 参考号或 MB WAY 请求，顾客仍需付款。Multibanco 详情会随此状态一起发送，包含在订单邮件和顾客的订单历史中。默认：待处理。

Payment on hold status: ifthenpay 报告了与订单不符的付款（金额、币种）、订单取消后收到的付款，或针对购物车已付款的订单所收到的付款。备注会说明原因。默认：待处理，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

高级

Test Mode: Credit Card 和 Multibanco 使用 ifthenpay 沙盒端点；不会扣除真实款项，您使用的是 ifthenpay 提供的测试密钥。MB WAY 没有沙盒：请使用 ifthenpay 提供的测试密钥进行测试。Confirm Order 步骤会显示 TEST MODE 标识。默认：关闭。

Debug Log: API 请求和回调会写入 OpenCart 日志文件夹（storage/logs）中的 ifthenpay_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会轮转。错误始终会被记录。密钥、防钓鱼密钥和完整手机号码永远不会被记录。默认：关闭。

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

Delete Data on Uninstall: 开启后，卸载扩展时会删除网关设置、防钓鱼密钥和日志。订单和 ifthenpay 付款记录始终保留。默认：关闭。

导入 / 导出

Export: Download JSON 会将设置保存为 JSON 文件。ifthenpay 密钥不会被导出。

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

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 ifthenpay）。在 Confirm Order 步骤，顾客会看到您的说明和该付款方式的提示。OpenCart 在此步骤创建订单，仍然没有状态。

在 OpenCart 4 中，顾客通过支付方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

Multibanco。顾客会看到 You will receive a Multibanco reference to complete the payment. 顾客点击 Confirm Order 后，扩展会为订单总额创建一个动态 Multibanco 参考号，订单获得 Awaiting payment status。订单成功页面会显示 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 payment status。订单成功页面会显示 A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. 收到回调后，订单即被标记为已付款。仅会保存脱敏后的手机号码。默认情况下，OpenCart 4 不会在结账时询问手机号码；该字段留空，由顾客输入号码。

Credit Card。顾客会看到 You will be redirected to a secure page to enter your card details.，并被转到 ifthenpay 的银行卡页面。订单保持无状态，购物车会被保留。付款成功后，顾客返回您的店铺。只有在返回信息带有有效的 ifthenpay 签名、该次尝试的密钥且订单存在银行卡请求时，返回才会被接受；随后订单被标记为已付款，顾客看到 OpenCart 的订单成功页面。如果无法验证返回信息，则不会有任何变化，并且会显示 Payment confirmation 页面，其中包含 Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed.，以及 Check again 和 Back to checkout 按钮；回调一到达就会确认付款。如果银行卡付款失败或被取消，顾客会返回结账页面，并看到 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. 订单的每一次银行卡尝试都会被保留，因此即使是在旧标签页中完成的付款也会被接受。在 OpenCart 4 中，这些消息会显示在结账页面上方。

付款确认后，订单将按 OpenCart 的标准方式获得状态，并发送常规的订单邮件。在 OpenCart 3 中，每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则更新结账中的订单，因此银行卡付款取消或失败后，或 MB WAY 请求被拒绝后，顾客会以新的尝试支付同一订单。如果同一购物车已有一笔已付款订单，或一笔正在等待 Multibanco 或 MB WAY 付款的订单，顾客将被引导至该订单的成功页面，而不是重新发起付款。仅当订单正在等待付款时，成功页面才会显示 Multibanco 详情和 MB WAY 提示。对购物车的更改（包括新的数量）会被视为需要单独付款的新购物车。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在此期间未付款即被关闭（例如，您取消了一笔等待 Multibanco 付款的订单），顾客会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. 如果订单已经下达，且之后购物车发生了变化，消息为 Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. 两种情况下，下一次 Confirm Order 都会为购物车支付一个新订单。

如果无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到一条简短提示，例如 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 status (missing order): 银行卡付款已发起但尚未确认，或已失败或被取消。在 Sales > Orders 中，此类订单只会在 Order Status 筛选器设置为 Missing Orders 时显示。

Awaiting payment status (default Pending): 已生成 Multibanco 参考号或已发送 MB WAY 请求。未付款的参考号和被拒绝的 MB WAY 请求不会自动取消订单；如有需要，请自行取消这些订单。

Order Status After Payment (default Processing): 付款已确认。备注会显示 Multibanco 参考号、MB WAY 交易或银行卡请求 ID，以及确认方式。

Payment on hold status (default Pending): 收到的金额与订单总额不同（例如，在开始银行卡付款后购物车被修改）、付款是在订单取消后到达的，或同一购物车的另一笔订单已经付款。备注会说明情况，并且不会要求顾客重新付款。请在 ifthenpay 后台检查付款，并手动完成或退款该订单。对于此类订单，后续的正确付款不会改变其状态。

已付款订单的第二笔付款只会添加一条备注，提示您在 ifthenpay 后台检查是否为重复付款。您已改为其他状态（例如已退款）的订单永远不会被重新打开；只会添加一条备注。

备注是订单 History 中的条目，顾客看不到。

VibeFox ifthenpay Gateway 选项卡

在 Sales > Orders 中打开一个通过 ifthenpay 付款的订单。在订单页面底部、History 和 Additional 旁边，VibeFox ifthenpay Gateway 选项卡会列出该订单的付款尝试（日期、方式、测试付款的 Sandbox 标签、金额、Multibanco 实体和参考号或脱敏的 MB WAY 手机号、ifthenpay 请求 ID 和状态），订单处于挂起状态时会显示 Payment on hold 警告，并显示该订单的 ifthenpay notes。该选项卡为只读，仅显示给有权访问该扩展的用户。

退款

不支持从 OpenCart 退款。请在 ifthenpay 后台退款，并在 OpenCart 中手动记录。Sales > Returns 中的商品退货不会通过 ifthenpay 退还款项。已退款（DEVOLVIDO）的回调只会添加一条备注。ifthenpay 报告的其他状态也只会添加备注。

许可证密钥

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

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

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

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

故障排除

结账时不显示 ifthenpay：请检查许可证是否有效，Enable/Disable 是否已开启，所选 Payment Method 的密钥是否已填写，顾客是否使用 EUR 付款，以及金额是否在 0.01 至 99,999.99 EUR 之间。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到了设置中的 Total。

顾客已付款，但订单仍处于等待状态或无状态：回调没有到达您的店铺。请检查 ifthenpay 是否已为您使用的密钥启用了回调 URL 和防钓鱼密钥，并确认该 URL 是所选付款方式对应的 URL。店铺必须可以从互联网访问，不能是 localhost，也不能位于登录页面之后。开启 Debug Log，并查看扩展页面上的 Log 字段。

回调返回 403 Forbidden：回调中的防钓鱼密钥缺失，或与设置中的不一致。请将设置中显示的密钥重新发送给 ifthenpay。

回调返回 503 Not configured：防钓鱼密钥尚未生成。请打开一次扩展设置；ifthenpay 会重试回调。

回调返回 503 Busy：同一订单当时正被另一个请求处理。ifthenpay 会重试回调。

回调返回 Order not found：该参考号或请求不属于本扩展的某笔付款，或者订单是使用其他付款方式下的。

为什么已付款订单会被挂起？收到的金额与订单总额不同、付款是在订单取消后到达的，或同一购物车的另一笔订单已经付款。请阅读 VibeFox ifthenpay Gateway 选项卡中的备注，在 ifthenpay 后台检查付款，并手动完成或退款该订单。

MB WAY 请求无法发送：手机号码未绑定 MB WAY，或格式错误。请使用 912 345 678；其他国家的号码请使用 351#912345678。

测试模式与 MB WAY：ifthenpay 没有 MB WAY 沙盒；请使用 ifthenpay 提供的测试密钥。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox ifthenpay Gateway 旁边的 Uninstall（红色的 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件和启动操作，即在维护模式下放行回调和顾客返回的启动操作）。如果 Delete Data on Uninstall 已开启，其余网关设置、防钓鱼密钥和日志都会被删除；重新安装后会生成新的防钓鱼密钥，必须再次发送给 ifthenpay。如果未开启，这些内容会保留，以便之后重新安装时使用。ifthenpay 付款记录（参考号和请求 ID）始终会保留，因此重新安装后，针对之前已签发参考号的回调仍能找到对应订单。已有订单会保留其付款备注。

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

ifthenpay 是其各自所有者的商标。本扩展与 ifthenpay 无关联，也未获得 ifthenpay 的认可或背书。