VibeFox iPay88 for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，且已安装并启用。若未安装 WooCommerce，插件无法启用。

PHP：8.0 或更高版本。

iPay88 商户账户：商户账户激活后，iPay88 会签发 Merchant Code 和 Merchant Key。它们也显示在 iPay88 商户后台中。如果您还不是商户，请在 iPay88 网站上申请。请妥善保管 Merchant Key：它用于签名付款请求。

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

店铺货币：Malaysia — MYR；如果您的 iPay88 账户已启用多币种选项，还可使用 USD、SGD、AUD、CAD、EUR、GBP、HKD、CNY、TWD、INR、IDR、PHP 或 THB；Philippines — PHP 或 USD；Indonesia — IDR；Thailand — THB。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_ipay88_payment 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > iPay88 > Manage，或在插件列表页点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 选择您的 iPay88 region，并输入 Merchant Code 和 Merchant Key（参见配置）。

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

配置

所有设置都在同一页面中：WooCommerce > Settings > Payments > iPay88。在字段上方，页面会在以下情况给出提示：缺少 Merchant Code 或 Merchant Key（此时结账时不会显示该付款方式）、店铺货币无法在所选地区收款，以及测试模式开启期间。在付款方式列表中，在两个密钥都填写之前，iPay88 会被标记为需要设置；测试模式开启期间，会显示测试模式标记。

常规

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

Title：顾客在结账时看到的付款方式名称。默认：iPay88。

Description：结账时显示在付款方式下方的文字。默认：Pay securely via iPay88 (credit card, online banking, e-wallet)。

iPay88 账户

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

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

Merchant Key：您的 iPay88 Merchant Key。它用于签名付款请求，并验证 iPay88 的响应。请妥善保管。

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 个字符。以数字结尾的前缀在保存时会被自动修正，因为订单号是从参考号的末尾读取的。

Test mode：Charge a fixed test amount instead of the order total。iPay88 没有独立的沙盒环境：测试付款是在正式的 iPay88 付款页面上以小额金额进行的真实交易（1.00；IDR 10,000）。收到测试金额后，订单会被标记为已付款，订单备注中会注明此情况。测试模式开启时，结账页面会显示 TEST MODE: only a test amount of ... will be charged.。切勿在正式运营的店铺中开启测试模式。默认：关闭。

响应与后台 URL

插件在每次付款时都会发送这两个 URL，因此无需配置。如果 iPay88 需要它们，可从设置的此部分复制。它们的格式类似：https://your-site/wc-api/ipay88_p_response/（Response URL，顾客返回）和 https://your-site/wc-api/ipay88_p_backend/（Backend URL，服务器对服务器的通知）。该部分还显示您的网站地址，它必须已在 iPay88 登记为 Request URL。

iPay88 的两种响应均按相同方式验证：使用您的 Merchant Key 生成的签名、本店铺为该订单发起的付款参考号、金额和货币。签名无效的请求会被拒绝，且绝不会修改订单。后台通知只有在处理完成后才会收到 RECEIVEOK 回复，否则 iPay88 会重新发送。iPay88 报告以下付款状态：

高级

Debug log：在 WooCommerce > Status > Logs 中，来源为 wcp_ipay88_payment 的 Log payment requests and iPay88 responses，不包含个人数据或签名。错误始终会被记录。默认：关闭。

Delete data on uninstall：Delete the settings, logs and iPay88 order data when the plugin is deleted。订单本身永远不会被删除。默认：关闭。

结账

顾客选择付款方式（默认为 iPay88）并提交订单。订单保持 Pending payment 状态，在表单被提交到您所在地区的 iPay88 付款页面期间，顾客会看到 Redirecting to iPay88 payment gateway...。在未启用 JavaScript 的情况下，顾客需点击 Pay Now。订单商品以及顾客的姓名、邮箱和电话会传递给 iPay88。在 iPay88 页面上，顾客可使用银行卡、FPX 网上银行、电子钱包或您的账户提供的其他方式付款。

付款后，顾客会返回您店铺的订单接收页面。只有当 iPay88 通过带签名的响应（无论是在顾客返回时，还是通过后台通知）确认付款后，订单才会被标记为已付款。如果确认信息尚未到达，页面会显示 We have not received the payment confirmation from iPay88 yet. If you completed the payment, your order will be updated shortly.。对于待处理的付款，页面会显示 Your payment is pending confirmation from iPay88. We will update your order as soon as the payment is confirmed.

如果付款失败或已取消，顾客会进入 Pay for order 页面，并显示 The payment was not completed: 以及 iPay88 给出的原因，此时顾客可以再次付款或选择其他付款方式。如果无法验证响应，顾客会看到 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. 以及返回店铺的链接。

库存在付款确认后才会扣减，而不是在顾客跳转时扣减。该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。

插件仅支持一次性付款。不支持 WooCommerce 退款、保存银行卡、订阅、预授权与扣款，也不支持您网站上的银行卡输入框。插件不会向 iPay88 重新查询付款状态：订单仅通过 iPay88 的响应和后台通知更新。不使用 iPay88 Indonesia API 2.0（JSON / 付款链接）。

订单

Order statuses

Pending payment：顾客已被转至 iPay88 但尚未付款，或 iPay88 尚未确认付款。

Processing or Completed：付款已确认。WooCommerce 会为已付款订单设置常规状态。订单备注显示 iPay88 的 TransID、PaymentID、金额和货币。交易 ID 即 iPay88 的 TransID。在测试模式下，第二条备注会说明收取的是测试金额，而非订单总额。

On hold, pending at iPay88：iPay88 报告付款待处理。待 iPay88 确认或使付款失败后，订单才会更新。

On hold, for review：iPay88 报告了一笔成功付款，但其金额或货币与订单不符，或付款是在订单取消之后到达的。订单未被标记为已付款。订单备注中会说明情况。请在 iPay88 后台核实付款，然后完成订单或退款。

Failed：付款失败或已取消。备注中显示 iPay88 给出的原因。顾客可以再次付款。

如果一个已付款或已退款的订单又收到另一笔成功付款，订单不会被改变。备注会提醒您在 iPay88 后台进行核实，如果属于重复付款则予以退款。失败的响应绝不会改变已付款、已退款或已取消的订单。

退款

退款不会从 WooCommerce 发送到 iPay88。请在 iPay88 商户后台退款，并在 WooCommerce 中手动记录退款。

许可证密钥

插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > iPay88 的顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将密钥从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，iPay88 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前进行设置和测试。插件列表页和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认。

许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

iPay88 未在结账时出现：请检查许可证是否有效、Enable/Disable 是否已开启、是否已填写 Merchant Code 和 Merchant Key，以及店铺货币能否在所选的 iPay88 region 中收款。设置页面在缺少内容时会显示警告。

付款已成功，但订单仍为 Pending payment：顾客返回和后台通知都没有带着有效签名到达您的店铺。请开启 Debug log，并查看 WooCommerce > Status > Logs，来源为 wcp_ipay88_payment。请确认 Merchant Key 与 iPay88 提供的完全一致，并且您的站点能够接收来自 iPay88 的请求，地址为设置中显示的 Backend URL。

iPay88 页面显示 "Permission not allow"：您的网站地址未在 iPay88 登记为 Request URL。请让 iPay88 登记 Response and backend URLs 部分中显示的地址。

后台通知返回 BAD SIGNATURE：签名与 Merchant Key 不匹配。请检查 Merchant Key。

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

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

订单处于 On hold，并附有关于金额或货币的备注：iPay88 报告的付款与订单不符，或订单已被取消。订单未被标记为已付款。请在 iPay88 后台核实该付款，并完成或退款。

顾客看到 "iPay88 cannot accept payments in" 加某种货币：订单货币无法在所选地区收款。在 iPay88 Malaysia 上，除 MYR 以外的货币还需要在您的 iPay88 账户中启用多币种选项。

真实顾客只被收取 1.00：Test mode 已开启。请关闭它。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已变更，请点击 Check now，以便为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最近一次已知的状态运行。

开发者可以使用以下过滤器修改付款页面 URL、货币、小数位数、测试金额和图标：ipay88_p_payment_url、ipay88_p_supported_currencies、ipay88_p_currency_decimals、ipay88_p_test_amount 和 ipay88_p_icon。

卸载

停用插件会保留所有数据。要移除插件，请在 Plugins 页面将其停用并删除。本插件的许可证密钥和许可证状态始终会被移除。只有在 Delete data on uninstall 已开启时，付款网关设置、日志以及保存在订单上的 iPay88 数据才会被移除；否则这些数据会保留，以便日后重新安装时使用。订单本身永远不会被删除，并会保留其付款备注和交易 ID。

iPay88 是其各自所有者的商标。本插件与 iPay88 无关联，也未获得 iPay88 的认可。