VibeFox iPay88 for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

iPay88 商户账户：Merchant Code 和 Merchant Key 在您的商户账户激活后由 iPay88 发出，也可在 iPay88 商户门户中查看。如果您还不是商户，请在 iPay88 网站上申请。请妥善保管 Merchant Key：它用于对付款进行签名。iPay88 没有独立的沙盒环境，因此没有测试密钥。

请求 URL：您的网站地址必须已在 iPay88 登记为请求 URL（request URL）。否则 iPay88 页面会显示 "Permission not allow"。

货币：马来西亚 — MYR；如果您的 iPay88 账户已启用多币种选项，还可使用 USD、SGD、AUD、CAD、EUR、GBP、HKD、CNY、TWD、INR、IDR、PHP 或 THB；菲律宾 — PHP 或 USD；印度尼西亚 — IDR；泰国 — THB。如果顾客的结账货币无法在您所在地区收款，付款方式将在结账时被隐藏。

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

安装

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

OpenCart 3

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

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

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

4. 选择您的 iPay88 region，输入 Merchant Code 和 Merchant Key，开启 Enable/Disable 并点击 Save。

5. 要检查设置，请在开启 Test mode 的情况下完成一笔付款，然后关闭测试模式。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥和 iPay88 设置。两个版本的设置页面及其字段相同。只有响应和后台 URL 不同（参见响应和后台 URL）。

新安装的扩展默认关闭付款方式。响应和后台 URL 会随每笔付款一起发送，因此无需在 iPay88 中为它们做任何设置。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox iPay88 Payment > Edit。各个部分列在左侧；列表下方的 Save 按钮保存整个页面。在设置上方，页面会在缺少密钥时显示 Enter the iPay88 Merchant Code and Merchant Key — until then the payment method is not shown at checkout.；当店铺默认货币无法在所选地区收款时会显示警告（此时该货币的结账页面会隐藏付款方式）；测试模式开启时也会显示警告。如果您没有修改该扩展的权限，页面会显示设置，但无法保存。

保存时，Title 不能超过 128 个字符，Sort Order 必须是整数，Total 必须是 0 或更大的数字，并且所选的地理区域和订单状态必须存在。否则不会保存任何内容，错误信息会指出对应字段。iPay88 相关字段永远不会阻止保存。

iPay88

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：iPay88。最多 128 个字符；如果留空，顾客将看到 iPay88。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely via iPay88 (credit card, online banking, e-wallet).

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

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

Total：订单必须达到的结账总额（以店铺默认货币计算），达到后才会提供 iPay88。留空则对任何金额都提供 iPay88。

iPay88 账户

iPay88 region：您的 iPay88 商户账户所属国家。它决定 iPay88 付款页面以及可收款的货币。订单始终以其自身货币收款。默认：Malaysia。

Merchant Code：您的 iPay88 Merchant Code，例如 M01234。

Merchant Key：您的 iPay88 Merchant Key。它用于对付款请求进行签名，并验证 iPay88 的响应。请妥善保密。保存时会去除开头和结尾的空格。已保存的密钥不会再次显示：该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选 Clear the saved Merchant Key on save，然后点击 Save。

Signature type：付款请求的签名方式。响应会以两种格式进行验证，因此在切换之前发起的付款仍可验证。

付款

Payment method：从马来西亚 PaymentId 列表中预选一种 iPay88 付款方式，或保留 Let the customer choose on the iPay88 page（默认）。该列表包括 Credit Card (MYR)、FPX (Online Banking)、Maybank2U、Alliance Online、AmBank、RHB Bank、Hong Leong Bank、CIMB Clicks、Web Cash、PayPal (MYR)、Credit Card (PHP)、Boost、Touch n Go eWallet、GrabPay 和 ShopeePay。

Reference prefix：可选。它会添加在 iPay88 参考编号（RefNo）中订单号之前，例如 SHOP1-。如果多个店铺使用同一个 iPay88 账户，请为每个店铺设置不同的前缀，以确保一个店铺的响应绝不会被应用到另一个店铺的订单上。可使用字母、数字、“-”和“_”，最多 10 个字符。保存时会删除其他字符；以数字结尾的前缀会在末尾加上“-”，因为订单号是从 RefNo 的末尾读取的。页面随后会用已保存的值向您发出提示。

Test mode：按固定的测试金额收款，而不是订单总额。iPay88 没有独立的沙盒环境：测试付款是在 iPay88 正式付款页面上进行的真实交易，金额很小（1.00；IDR 10,000）。收到测试金额后，订单会被标记为已付款，订单备注中也会注明。测试模式开启时，顾客在 Confirm Order 步骤会看到 TEST MODE: only a test amount of ... will be charged. 在测试模式下发起的付款，即使您在 iPay88 响应之前关闭了测试模式，也始终按测试金额进行核对。切勿在正式店铺中开启测试模式。默认：关闭。

响应和后台 URL

扩展会随每笔付款发送这两个 URL，因此无需进行任何配置。如果 iPay88 要求提供这些地址，请从本部分复制。在 OpenCart 3 中，它们的格式类似 https://your-store/index.php?route=extension/payment/wcp_ipay88_payment/back（Response URL，顾客的返回）和 https://your-store/index.php?route=extension/payment/wcp_ipay88_payment/backend（Backend URL，服务器到服务器的通知）；在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_ipay88_payment/payment/wcp_ipay_88payment.back 和 https://your-store/index.php?route=extension/wcp_ipay88_payment/payment/wcp_ipay_88payment.backend。本部分还会显示您的网站地址，该地址必须在 iPay88 登记为请求 URL。

iPay88 的两种响应都以相同方式检查：必填字段、用您的 Merchant Key 生成的签名，以及本店铺为该订单发起的付款的参考编号。签名无效的响应会被拒绝，并且绝不会更改订单。后台通知只有在处理完成后才会以 RECEIVEOK 回复；否则 iPay88 会重新发送。即使店铺处于维护模式，它也能正常工作：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动动作，放行签名后的后台通知和顾客的返回请求。iPay88 会报告以下付款状态：

订单

OpenCart 在 Confirm Order 步骤创建订单，此时订单没有状态（缺失订单，missing order）。只有在 iPay88 发送了正确签名的响应之后，订单才会获得状态。失败或取消的付款会使订单保持无状态；顾客会返回结账页面，购物车会保留。下面每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：金额和币种均符合预期的成功付款（iPay88 状态 1）。默认：Processing。

Awaiting Payment Status：等待中的付款（状态 6），例如顾客尚未完成的 ATM 或虚拟账户转账。iPay88 确认后，订单会转为付款后状态。默认：Pending。

On Hold (Review) Status：iPay88 报告了一笔成功付款，但金额或币种与订单不符，或者订单已被取消。备注会显示详情；订单不会被标记为已付款。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Failed Payment Status：一笔等待中的付款（状态 6），之后 iPay88 报告其失败（状态 0）。默认：Failed。

Cancelled Order Status：您的店铺用于已取消订单的状态。对此类订单收到的付款会将其置于审核状态，而不是标记为已付款。扩展绝不会自行设置此状态。默认：Canceled。

高级

Debug log：将付款请求和 iPay88 响应记录到 OpenCart 日志文件夹（storage/logs）中的 ipay88_p_debug.log.php。该文件无法通过网页打开。不会记录个人数据、Merchant Key 或签名。错误和警告始终会被记录，即使开关已关闭。默认：关闭。

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

Delete data on uninstall：开启后，卸载扩展会删除设置和日志。订单和 iPay88 付款记录永远不会被删除，因此即使在重新安装后，对旧付款的延迟响应仍会被处理。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。Merchant Key 不会被导出。

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 iPay88）。在 Confirm Order 步骤中，顾客看到您的说明。OpenCart 在此步骤创建订单，此时仍无状态。当顾客点击 Confirm Order 时，该步骤会显示 Redirecting to iPay88 payment gateway... 和 Please do not close this window.，同时将一份已签名的表单发送到您所在地区的 iPay88 付款页面。如果浏览器没有自动发送该表单，顾客可点击 Pay Now。扩展会以订单货币传递订单总额（测试模式下为测试金额）、商品名称，以及顾客的姓名、电子邮件和电话。在 iPay88 页面上，顾客可以使用银行卡、FPX 网银、电子钱包，或您的账户提供的其他付款方式。

在 OpenCart 4 中，顾客在付款方式区块中点击 Choose 按钮选择付款方式（位于 Payment method options 窗口中），然后点击结账页面底部的 Confirm Order。OpenCart 4 默认不在结账时要求电话，但 iPay88 需要：如果订单没有电话，确认步骤会显示必填的 Phone 字段，并附上 iPay88 requires the contact number of the payer. 若未填写号码，顾客会看到 iPay88 requires a phone number. Please enter your phone number and try again. 所输入的号码会保留，用于下一次尝试。

只有当 iPay88 通过已签名的响应（无论是在顾客返回时，还是通过后台通知）确认付款后，订单才会被标记为已付款。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。付款成功后，顾客会看到 OpenCart 的订单成功页面，并显示 Your iPay88 payment has been received. 对于待处理的付款，页面会显示 Your payment is pending confirmation from iPay88. We will update your order as soon as the payment is confirmed. 对于处于审核中的订单，页面会显示 We have received a payment notification from iPay88 and are reviewing it. We will contact you if anything is needed. 当待处理的付款之后被确认或失败时，OpenCart 会将新状态通知顾客。

如果订单同时正在由后台通知确认，顾客会看到 We have not received the payment confirmation from iPay88 yet. If you completed the payment, your order will be updated shortly. 并带有 Check again 和 Back to checkout 按钮。

如果付款失败或被取消，订单保持无状态，购物车会保留。顾客会返回结账页面，显示 The payment was not completed: 以及 iPay88 给出的原因，随后是 You can try again or choose another payment method. 在 OpenCart 4 中，此消息显示在结账页面上方。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，因此也会生成一个新的 RefNo；OpenCart 4 则会更新结账的订单，因此顾客会再次支付同一订单。同一订单的重新尝试会使用相同的 RefNo。如果无法验证响应，顾客会看到 The payment response could not be verified. If you completed the payment, please contact us with your order number — the payment will be checked manually. 并带有 Return to the store 按钮。

如果付款无法发起，顾客会停留在 Confirm Order 步骤，并看到 This payment method is temporarily unavailable. Please choose another payment method.（密钥缺失或总额为零），或 iPay88 cannot accept payments in ... Please choose another payment method.（该货币无法在该地区收款）。同一购物车只能付款一次：如果同一购物车的另一个订单已经付款或正在等待待处理的付款，则不会创建第二个付款表单，顾客将被带到订单成功页面。购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在未付款的情况下已被关闭（例如待处理的转账失败，或您取消了订单），顾客会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. 如果订单已经生成且购物车已变化，提示为 Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. 两种情况下，下一次点击 Confirm Order 都会为购物车支付一个新订单。

该扩展仅支持一次性付款。它不支持从 OpenCart 退款、保存银行卡、订阅、预授权与扣款，也不支持在您的网站上设置银行卡输入框。它不会向 iPay88 重新查询付款状态：订单仅通过 iPay88 的响应和后台通知进行更新。

订单

订单状态

No status (missing order)：顾客已被转到 iPay88，但尚未收到任何结果，或者付款失败。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时才会显示这类订单。

Order Status After Payment（默认 Processing）：iPay88 报告付款成功，且金额和币种符合预期。备注会显示 TransID、PaymentID、金额和币种。在测试模式下，第二条备注会说明收取的是测试金额，而不是订单总额。

Awaiting Payment Status（默认 Pending）：iPay88 将付款报告为待处理。iPay88 确认后，订单会转为 Order Status After Payment；如果付款失败，则转为 Failed Payment Status。

Failed Payment Status（默认 Failed）：待处理的付款之后失败。备注会显示 iPay88 给出的原因。顾客可以重新下单。

On Hold (Review) Status（默认 Pending）：iPay88 报告了一笔成功付款，但金额或币种与订单不符，或者付款是在订单取消之后到达的。订单并未被标记为已付款。备注会对此作出说明。请在 iPay88 商户门户中核实付款，然后完成订单或退款。

已付款或已完成的订单绝不会因之后的响应而改变。如果同一订单，或同一购物车中的其他订单又收到一笔成功付款，备注会提示您在 iPay88 商户门户中核实，如属重复付款则予以退款。失败响应绝不会改变已付款、已取消或处于审核中的订单。重复的响应不会带来任何新内容。

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

VibeFox iPay88 Payment 选项卡

在 Sales > Orders 中打开一个通过 iPay88 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox iPay88 Payment 选项卡会显示 RefNo、TransId、Status、Requested 金额、Amount received、PaymentId、AuthCode、Error 和 Region，测试付款会带有 TEST MODE 标记，并显示该订单的 iPay88 notes。该选项卡仅对有权访问该扩展的用户显示。

退款

OpenCart 不会将退款发送给 iPay88。请在 iPay88 商户门户中退还付款，然后在 OpenCart 中手动记录退款。

许可证密钥

该扩展需要来自 vibefox.net 的 VibeFox 许可证密钥才能使用。许可证区块 License — VibeFox iPay88 Payment 是 Extensions > Extensions > Payments > VibeFox iPay88 Payment > Edit 页面中设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以遮罩形式显示密钥，并显示状态（例如许可证有效期截止日期以及您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-payment-ipay88 一行，以及打开您 vibefox.net 账户的 Manage licenses and domains in your account 链接。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。在店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用上一次已知的状态运行。

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

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

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

故障排除

结账时没有显示 iPay88：请检查许可证是否有效、Enable/Disable 是否开启、Merchant Code 和 Merchant Key 是否已填写，以及顾客的结账货币能否在所选的 iPay88 region 中收款。缺少内容时，设置页面会显示警告。另请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：顾客的返回和后台通知都没有带着有效签名到达您的店铺。请查看 Log 字段：错误始终会被记录。请检查 Merchant Key 是否与 iPay88 提供的完全一致，以及您的服务器是否接受来自 iPay88 的、发送到设置中所示 Backend URL 的请求。

iPay88 页面显示 "Permission not allow"：您的网站地址尚未在 iPay88 登记为请求 URL。请让 iPay88 登记 响应和后台 URL 部分所示的地址。

后台通知回复 BAD SIGNATURE：签名与 Merchant Key 不匹配。请检查 Merchant Key。未做任何更改。

后台通知回复 NOT CONFIGURED：未设置 Merchant Code 或 Merchant Key，因此无法验证响应。iPay88 会重新发送通知。

后台通知回复 UNKNOWN ORDER：本店铺没有为该参考编号发起过 iPay88 付款，例如使用同一账户的另一家店铺没有设置 Reference prefix，或设置了相同的前缀。

后台通知回复 RETRY：该订单（或同一购物车的另一个订单）正在被顾客返回或另一个通知同时确认，或者无法设置订单状态。iPay88 会重新发送通知。

Backend URL 在浏览器中显示 BAD REQUEST：这是正常现象。该 URL 只接受来自 iPay88 的已签名请求。

订单处于 On Hold (Review) Status：iPay88 报告的付款与订单不符，或订单已被取消。请阅读 VibeFox iPay88 Payment 选项卡中的备注，并在 iPay88 商户门户中核实付款，然后完成订单或退款。

顾客看到 "iPay88 cannot accept payments in" 和某种货币：结账货币无法在所选地区收款。在 iPay88 马来西亚，MYR 以外的货币还需要在您的 iPay88 账户中启用多币种选项。

顾客看到 This payment method is not available. Please reload the checkout page.：结账会话已与订单不再匹配，或付款方式在此期间被关闭。顾客需要重新加载结账页面。

真实顾客只被扣了 1.00：Test mode 已开启。请将其关闭。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox iPay88 Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装后会恢复默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还包括其事件和启动动作，该动作在维护模式下放行 iPay88 响应）。如果 Delete data on uninstall 已开启，其余设置（标题、说明、地区、Merchant Code 和 Key、签名类型、付款方式、前缀、测试模式、调试日志开关）和日志都会被删除。如果未开启，这些设置会保留，供以后重新安装时使用。订单的 iPay88 付款记录总会被保留。订单永远不会被删除，并会保留其付款备注。

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

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