VibeFox SimplePay for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法启用。

PHP：8.0 或更高版本。

商店币种：HUF、EUR 或 USD。SimplePay 不接受其他币种，因此不会为这些币种提供该付款方式。

SimplePay 商户账户：SimplePay 为每种币种提供单独的商户账户，并为正式与沙盒分别提供账户。每个账户都需要从 SimplePay 商户后台获取其 MERCHANT 和 SECRET KEY（正式环境为 admin.simplepay.hu，沙盒为 sandbox.simplepay.hu），路径为账户 > 技术数据。如果您只以 HUF 销售，HUF 账户即可。不需要其他密钥。

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

安装

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

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > SimplePay (OTP) > Manage，或在插件页面上点击插件名称下方的 Settings。

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

5. 为您销售的每种币种输入您的 SimplePay 账户的 MERCHANT 和 SECRET KEY：测试使用沙盒账户，真实付款使用正式账户（参见配置）。

6. 将设置页面上显示的 IPN URL 复制到 SimplePay 商户后台的每个商户账户（正式和沙盒）中。

7. 开启 Enable/Disable，在开启 Sandbox mode 的情况下测试付款，然后取消勾选 Sandbox mode 以接受真实付款。

从 1.0 版本升级时，1.0 中的单一 Merchant ID 和 Secret key 会被移入当前激活模式（沙盒或正式）下商店币种的账户。升级后请检查这些账户。

配置

所有设置都位于同一页面：WooCommerce > Settings > Payments > SimplePay (OTP)。在字段上方，如果商店币种不受 SimplePay 支持，或商店币种在当前模式下没有商户账户，页面会发出警告。在这两种情况下，都不会为该币种的订单提供此付款方式。开启沙盒模式时，页面会显示 Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged. 在付款方式列表中，直到当前模式至少有一个商户账户为止，SimplePay 都会标记为需要设置。

常规

Enable/Disable：Enable SimplePay Gateway 用于启用或禁用该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。默认：SimplePay (Card Payment)。

Description：结账时付款方式下方显示的文字。默认：Pay securely with your credit or debit card via SimplePay。匈牙利商户必须在结账时显示 SimplePay 数据传输声明（Adattovábbítási nyilatkozat）。您可以将其连同链接一起放在这里。

Sandbox mode：Use the SimplePay sandbox 会将付款发送到 SimplePay 沙盒，并使用沙盒账户。它会同时切换 API 地址和商户账户。不会收取真实款项。默认：开启。取消勾选即可使用正式账户接受真实付款。

正式商户账户

当 Sandbox mode 关闭时使用的账户。请填写您店铺所售币种的账户。MERCHANT 和 SECRET KEY 的值位于 SimplePay 商户后台（admin.simplepay.hu）的账户 > 技术数据中。只有两个字段都填写后，账户才会被使用。

HUF account — Merchant ID：您的正式 HUF 账户的 MERCHANT。

HUF account — Secret key：您的正式 HUF 账户的 SECRET KEY。

EUR account — Merchant ID 和 EUR account — Secret key：您的正式 EUR 账户同样填写。

USD account — Merchant ID 和 USD account — Secret key：您的正式 USD 账户同样填写。

沙盒商户账户

Sandbox mode 开启时使用的账户。字段与正式账户相同：HUF account — Merchant ID、HUF account — Secret key，以及 EUR 和 USD 的相同字段组。请从 SimplePay 沙盒商户后台（sandbox.simplepay.hu）的账户 > 技术数据中获取这些值。

IPN URL

IPN 是 SimplePay 在付款状态变化时发送给您店铺的消息，是订单变为已付款的常规途径。设置页面会显示您店铺的 IPN URL，格式类似 https://your-site/wc-api/simplepay_payment_callback/。请在 SimplePay 商户后台为每个商户账户（正式和沙盒）设置此 URL。如果您的站点在 URL 中使用语言前缀，或会重定向其他地址，请完全按照设置中显示的方式复制该 URL，因为被重定向的 IPN 会丢失。

IPN 必须使用其指定的商户账户的 SECRET KEY 签名。没有有效签名的 IPN 会被拒绝。插件会以 SimplePay 要求的签名格式向 SimplePay 确认每个有效的 IPN。以下 IPN 状态会改变订单：

FINISHED：付款成功。经过金额和币种核对后，订单标记为已付款。

NOTAUTHORIZED, FRAUD：付款被拒绝。订单变为失败。

TIMEOUT, CANCELLED：付款时间已过或顾客取消付款。订单变为已取消。

只有当订单仍处于等待付款状态时，才会为其最新一次付款尝试设置失败和已取消。其他状态会被记录到日志中，但不会改变订单。若没有 IPN，只有在顾客付款成功后返回店铺时，订单才会被确认。

订单

Order Status After Payment：付款成功后设置的订单状态。状态会立即设置，不会再次变更。

WooCommerce default (Processing; Completed for virtual/downloadable orders)：默认设置。

Completed：每个已付款订单都会变为已完成。

高级

Logging：Enable logging 会将 API 调用、IPN 和返回记录写入 WooCommerce > Status > Logs，来源为 wcp_simplepay_gateway。密钥和顾客数据不会被记录。即使此选项关闭，错误也始终会被记录。默认：关闭。

Delete Data on Uninstall：Remove all plugin data when uninstalling。开启后，删除插件时会移除网关设置和插件日志。订单数据始终保留。默认：关闭。

结账

顾客选择付款方式（默认为 SimplePay (Card Payment)）并下单。插件会以订单币种为订单总额发起 SimplePay 银行卡付款，使用当前模式下该币种的商户账户，并将顾客转到 SimplePay 付款页面。该页面会显示您的商户账户允许的银行卡付款选项。顾客的电子邮件以及（若已填写完整）账单地址会传递给 SimplePay。若 SimplePay 支持您站点的语言，付款页面将使用该语言，否则使用英文。已发起的付款可在 30 分钟内完成。

付款成功后，顾客会返回您店铺的订单已收到页面。仅返回本身绝不会让订单付款：插件会通过经签名的请求向 SimplePay 查询交易状态，因此即使 IPN 延迟到达，订单也会被确认。订单已收到页面会显示 Successful transaction. SimplePay transaction ID: 及其 ID。如果付款尚未确认，则显示 Your payment is being confirmed by SimplePay. SimplePay transaction ID: 及其 ID。

如果付款失败、被取消或超时，顾客会被送回结账页面；如果购物车为空，则会被送到 Pay for order 页面。在那里，顾客会看到 SimplePay 的提示信息及交易 ID，例如 Cancelled payment. You cancelled the payment 或 Timeout. The time allowed to complete the payment has expired。付款失败时，会提示顾客检查所输入的信息并联系发卡银行。顾客可以重试。每次新的尝试都会获得自己的 SimplePay 参考号，例如 123、123-2、123-3。

如果 SimplePay 无法发起付款，顾客会看到 The SimplePay payment could not be started. Please try again or choose another payment method. 如果订单币种没有商户账户，提示信息为 SimplePay is not available for the currency of this order. Please choose another payment method. 技术原因会添加到订单备注和日志中。已登录的店铺管理员也会在提示信息中看到该原因。

该付款方式适用于经典结账、结账区块以及 Pay for order 页面，并兼容 WooCommerce 高性能订单存储（HPOS）。

插件只接受一次性银行卡付款，并在 SimplePay 页面完成扣款。不支持保存银行卡或一键付款、订阅或定期付款，也不支持单独的授权与扣款。

订单与退款

订单状态

Pending payment：顾客已被转到 SimplePay 但尚未付款，或 SimplePay 尚未确认付款。订单备注会显示已发起的交易、金额及模式（沙盒或正式）。

Processing or Completed：付款已确认。状态遵循 Order Status After Payment 设置。订单备注会显示交易 ID，以及付款是由 IPN 还是状态查询确认的。SimplePay 交易 ID 会保存为订单的交易 ID。延迟到达的成功付款也会完成原本为失败或已取消的订单。

On hold：付款开始后订单总额或币种被修改，因此已付金额与订单不符。订单备注会显示两个金额。请检查订单，然后处理订单或退款。

Failed：SimplePay 报告最新一次付款尝试未获授权或属于欺诈。

Cancelled：SimplePay 报告最新一次付款尝试已超时或被取消。

已退款或已完成的订单不会因延迟的 IPN 而重新打开。如果已付款的订单又有第二笔付款成功，订单不会再次被修改。备注会提醒您在 SimplePay 后台检查，如果是重复付款则予以退款。

退款

打开订单，点击 Refund，输入金额后点击 Refund via SimplePay (OTP)。支持全额和部分退款。HUF 退款必须为整数福林。退款会使用付款时所用的商户账户和模式（沙盒或正式）发送，因此该账户必须仍保留在设置中。如果 SimplePay 不接受退款，WooCommerce 会显示错误，且不会记录退款。退款成功后，会在订单备注中添加 SimplePay 退款交易 ID；如果您填写了原因，也会一并添加。

在 SimplePay 商户后台进行的退款不会同步到 WooCommerce。请不要使用 Refund via SimplePay (OTP)，而是在 WooCommerce 中手动记录。

许可证密钥

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

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

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

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

故障排除

结账时看不到 SimplePay：请检查许可证是否有效、Enable/Disable 是否开启、订单币种是否为 HUF、EUR 或 USD，以及该币种在当前模式下是否同时有 Merchant ID 和 Secret key：Sandbox mode 开启时使用沙盒账户，关闭时使用正式账户。如果商店币种没有账户，设置页面会显示警告。

付款已完成，但订单仍为等待付款：IPN 未能到达店铺。请在 SimplePay 商户后台检查您所用商户账户（正式或沙盒，订单币种）的 IPN URL。它必须与设置中显示的 URL 完全一致，并且您的服务器必须可以从互联网访问。顾客付款后返回店铺时，订单也会被确认。

IPN 返回 Invalid signature：IPN 指定的商户账户不在设置中，或其 Secret key 有误。请按照 SimplePay 商户后台显示的内容，准确输入 MERCHANT 和 SECRET KEY。SimplePay 会重复发送未确认的 IPN。

IPN 返回 Order not found 或 Unknown transaction：该 IPN 对应的订单或交易不是由本店铺发起的。订单不会被修改。

IPN 返回 Busy, retry：该订单正在被另一个请求确认。SimplePay 会重试 IPN。

顾客下单时看到错误：请查看订单备注，或前往 WooCommerce > Status > Logs，来源为 wcp_simplepay_gateway。错误的 secret key 会导致 Invalid response signature from SimplePay. Check the secret key of the merchant account. SimplePay 的错误会以 SimplePay error code(s)： 加上错误代码的形式显示。

在沙盒与正式模式之间切换后：新付款使用新模式的账户。切换前发起的订单会保留其发起时所用的商户账户和模式：它们的 IPN、状态查询和退款都会使用该账户。在此类订单仍未关闭或可能需要退款期间，请在设置中保留旧模式的账户。

付款后订单变为 On hold：请阅读订单备注。付款开始后订单总额或币种已被修改。请处理订单或退款。

退款失败：请阅读提示信息。SimplePay refunds in HUF must be whole amounts. 表示 HUF 金额包含小数。如果提示信息显示该付款的商户账户未配置，请重新输入付款时所用的账户（币种和模式）。如果 SimplePay 退还的金额不同，提示信息会要求您在 SimplePay 后台检查该退款。

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

卸载

停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。只有开启了 Delete Data on Uninstall，网关设置和插件日志才会被删除；否则会保留，以便日后重新安装时使用。现有订单会保留其付款备注、交易 ID 和 SimplePay 数据。

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