VibeFox ePay.bg for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。

PHP：8.0 或更高版本。

店铺币种：保加利亚列弗（BGN）、欧元（EUR）或美元（USD）。订单以其自身币种扣款，保留 2 位小数。对于其他币种，该付款方式会在结账页面隐藏。

ePay.bg 账户：您需要从 ePay.bg 商户资料中获取客户编号（MIN）和密钥：正式的来自 www.epay.bg，测试的来自 demo.epay.bg（测试账户需单独注册）。您还需要在商户资料中填写店铺的通知 URL。

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

安装

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

2. 点击 Activate。WooCommerce 必须处于启用状态。

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

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

5. 输入测试和/或正式的 MIN 与密钥（见“配置”）。

6. 将 Payment notifications (IPN) 部分显示的通知 URL 复制到 ePay.bg 商户资料的 URL for receiving notifications 字段中，演示资料和正式资料都要填写。否则订单会一直处于待付款状态。

7. 开启 Enable/Disable。在测试模式下提交一个测试订单，然后取消勾选 Test Mode。

配置

所有设置都在同一个页面：WooCommerce > Settings > Payments > ePay.bg。在各字段上方，页面会在店铺币种不是 BGN、EUR 或 USD 时显示错误；在网关已启用但所选模式的 MIN 或密钥为空时显示警告（此时该付款方式会在结账页面隐藏，保存时也会显示同样的错误）；测试模式开启期间还会显示 Test mode is on: payments go to demo.epay.bg and no real money is charged. 在付款方式列表中，在输入所选模式的凭据之前，ePay.bg 会被标记为需要设置。

常规

Enable/Disable：Enable ePay.bg Payment Gateway 用于开启或关闭该付款方式。默认值：关闭。

Title：顾客在结账页面看到的付款方式名称。默认值：ePay.bg。

Description：在结账页面显示于付款方式下方的文字。默认值：Pay securely via ePay.bg with a bank card or your ePay.bg account.

ePay.bg 账户

客户编号（MIN）和密钥显示在您位于 www.epay.bg（正式）和 demo.epay.bg（测试账户，单独注册）的商户资料中。粘贴的密钥中的空格和换行符会在保存时被删除。

Test Mode：Enable test mode (use demo.epay.bg and the test credentials)。开启时，顾客会被转到 ePay.bg 演示环境，请求使用测试凭据签名。默认值：开启。

Test Merchant ID (MIN)：您的 demo.epay.bg 商户账户的客户编号（MIN）。

Test Secret Key：您的 demo.epay.bg 商户账户的密钥（64 个字符）。

Live Merchant ID (MIN)：您的 www.epay.bg 商户账户的客户编号（MIN）。

Live Secret Key：您的 www.epay.bg 商户账户的密钥（64 个字符），用于 HMAC-SHA1 签名。

如果您从 1.0 版升级，且当时测试模式处于开启状态，该版本中的单组凭据会被移到测试字段中。

付款通知（IPN）

通知会告知您的店铺某个付款请求已付款、被拒绝或已过期。此部分会显示通知 URL，格式类似 https://your-site/wc-api/epaybg_payment_callback/。请将其作为 URL for receiving notifications 填写到 ePay.bg 商户资料中，正式和测试资料都要填写。订单只会由这些已签名的通知标记为已付款；顾客返回店铺不会将订单标记为已付款。

ePay.bg 会针对每张发票报告以下结果：

每条通知都会使用所选模式的密钥进行校验。没有有效校验和的通知会被拒绝，ePay.bg 会继续发送。如果商户资料中没有通知 URL，则不会有任何订单被标记为已付款。

付款请求

Invoice Prefix：仅限数字（最多 10 位），放在订单 ID 前面，组成 ePay.bg 发票号，例如 00001 + 123 = 00001123。同一个 ePay.bg 账户下的不同店铺请使用不同的前缀。其他字符会在保存时被删除。之后更改前缀是安全的：待处理订单是通过订单上保存的发票找到的。默认值：00001。

Expiration Time：未付款的付款请求过期的时间；到期后 ePay.bg 会报告其已过期，待付款订单随即被取消。可选择 1、3、6、12、24、48 或 72 小时。无论您网站的时区是什么，时间都按保加利亚时间发送。默认值：24 小时。

Language：ePay.bg 付款页面的语言，英语或保加利亚语。默认值：英语。

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

高级

Logging：Enable logging 会将付款请求和通知写入 WooCommerce > Status > Logs，来源为 wcp_epaybg_gateway，不含密钥或银行卡数据。默认值：关闭。

Delete Data on Uninstall：Remove all plugin data when uninstalled。勾选后，卸载插件时会删除网关设置、订单上保存的 ePay.bg 数据以及插件日志。默认值：关闭。

结账

顾客选择付款方式（默认为 ePay.bg）并下单。顾客会看到 Redirecting to ePay.bg for payment...，并带着一个已签名的付款请求被转到 ePay.bg，请求中包含以订单币种表示的订单总额、发票号和过期时间。页面上还有一个 Pay via ePay.bg 按钮（以防自动跳转未启动）和一个 Cancel order 按钮。在 ePay.bg，顾客使用银行卡或 ePay.bg 账户付款。

付款后，顾客会返回您店铺的订单已收到页面。只有当已签名的 ePay.bg 通知到达时，订单才会被标记为已付款。购物车只会在订单已收到页面清空。

如果顾客在 ePay.bg 取消，订单会按 WooCommerce 的标准方式取消，购物车会保留，因此顾客可以选择其他付款方式。

如果订单无法通过 ePay.bg 付款，顾客会看到一条简短的消息，例如 ePay.bg payments are temporarily unavailable. Please choose another payment method.，或提示 ePay.bg 不接受订单币种的付款。

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

插件仅支持在 ePay.bg 上进行一次性付款。不支持在 WooCommerce 中退款，不支持保存银行卡或令牌化，不支持订阅或定期付款，也不支持 EasyPay 或 B-Pay 现金付款码。

订单

订单状态

Pending payment：顾客已被转到 ePay.bg 但尚未付款，或通知尚未到达。订单备注为 Awaiting ePay.bg payment.

Processing, Completed or On Hold：付款已确认。状态遵循 Order Status After Payment 的设置。订单备注会显示发票号、付款日期、STAN 和 BORICA 代码。交易 ID 为 STAN（若没有 STAN，则为发票号）。

On hold after payment：付款已到达，但与订单当前内容不符：付款请求之后订单的总额或币种被更改；请求是在另一种模式下发出的，或网关之后在测试和正式之间切换过；订单的付款方式被更改；或订单此前已被取消。订单备注会说明原因。请在 ePay.bg 商户面板中核对该笔付款，并手动完成订单或退款。

Cancelled：ePay.bg 报告付款请求被拒绝或已过期，或顾客在 ePay.bg 取消了付款。WooCommerce 会恢复库存。已取消的订单无法再次付款，因为 ePay.bg 发票号是前缀加订单 ID。顾客需要重新下单。

迟到的拒绝或过期通知绝不会更改已付款订单。如果已付款或已退款的订单又收到一笔付款，状态不会改变，并且会有一条备注提示您在 ePay.bg 商户面板中检查是否重复付款。

退款

无法在 WooCommerce 中退款，因为 ePay.bg WEB API 没有退款调用。请在 ePay.bg 商户面板中为该笔付款退款，然后在 WooCommerce 中手动记录退款。

许可证密钥

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

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

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

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

故障排除

结账页面不显示 ePay.bg：请检查许可证是否有效、Enable/Disable 是否已开启、所选模式的 MIN 和密钥是否已填写，以及店铺币种是否为 BGN、EUR 或 USD。设置页面会在上述每种情况下显示警告。

付款已完成，但订单仍为待付款：订单只会由 ePay.bg 通知标记为已付款。请检查通知 URL 是否已填写在您所用模式（演示或正式）的 ePay.bg 商户资料中，以及当前模式的密钥是否正确。开启 Logging，然后查看 WooCommerce > Status > Logs，来源为 wcp_epaybg_gateway。

通知返回 ERR=Not valid CHECKSUM：设置中的密钥与发送通知的商户资料不匹配。通知会先用当前所选模式的密钥校验，再用另一模式的密钥校验，因此切换模式之前发出的付款请求仍会被接受。ePay.bg 会持续重试，所以密钥正确后订单就会更新。

通知返回 ERR=Not configured：所选模式的密钥为空。请填写密钥。

通知针对某张发票返回 STATUS=NO：该发票不属于本店铺的 ePay.bg 订单，例如它是由同一 ePay.bg 账户下的另一家店铺开具的。请为每家店铺设置各自的 Invoice Prefix。

通知返回 STATUS=ERR：临时错误，例如同一订单在同一时刻收到两条通知。ePay.bg 会再次发送通知。

付款后订单为保留状态：请阅读订单备注。可能是付款请求之后总额或币种发生了变化，请求是在另一模式下发出的或之后切换了模式，付款方式发生了变化，或订单曾被取消。请在 ePay.bg 商户面板中核对该笔付款。

保存时发票前缀被更改：前缀只能包含数字，最多 10 位。其他字符会被删除。

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

对于开发者，readme 中提到了过滤器 epay_bp_form_fields，例如用于使用直接银行卡页面（PAGE=credit_paydirect）。

卸载

停用插件会保留所有数据。要移除插件，请在 Plugins 页面先停用再删除。此插件的许可证密钥和许可证状态总会被删除。网关设置、订单上保存的 ePay.bg 数据以及日志，仅在 Delete Data on Uninstall 已开启时才会被删除；否则会保留，以便日后重新安装。现有订单会保留其付款备注和交易 ID。

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