VibeFox ePay.bg for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：保加利亚列弗（BGN）、欧元（EUR）或美元（USD）。订单以其自身货币扣款，保留 2 位小数。当顾客以其他货币结账时，付款方式会被隐藏。

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

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

安装

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

OpenCart 3

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

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

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

4. 填写测试和/或正式环境的 MIN 和密钥（参见配置）。

5. 将 Payment notifications (IPN) 部分显示的 URL 复制到 ePay.bg 商户资料的 URL for receiving notifications 字段中，demo 和正式商户资料都需要填写。否则没有任何订单会获得状态。

6. 开启 Enable/Disable 并点击 Save。在测试模式下下一个测试订单，然后关闭 Test Mode。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 中第 3 至 6 步的方式填写许可证密钥、ePay.bg 凭据和通知 URL。设置页面及其字段在两个版本中相同。仅通知 URL 不同（参见付款通知（IPN））。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果店铺的默认货币不是 BGN、EUR 或 USD，页面会显示错误；如果付款方式已启用但所选模式的 MIN 或密钥为空，页面会显示警告（此时结账时会隐藏该方式，保存时也会显示同样的警告）；而测试模式开启时，页面会显示 Test mode is on: payments go to demo.epay.bg and no real money is charged. 没有修改扩展的权限时，页面会显示设置但无法保存。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数，Total 必须为 0 或更大的数字；如有任何字段错误，则不会保存任何内容。

ePay.bg

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：ePay.bg。必填。

Description：在 Confirm Order 步骤向顾客显示的文字。默认：Pay securely via ePay.bg with a bank card or your ePay.bg account.

Sort Order：ePay.bg 在结账时的付款方式中的位置。留空或输入整数。

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

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

ePay.bg 账户

客户编号（MIN）和密钥显示在您在 www.epay.bg（正式）和 demo.epay.bg（测试账户，需单独注册）上的商户资料中。

Test Mode：启用测试模式。顾客会被转到 ePay.bg 演示环境，请求使用测试凭据签名。默认：开启。开启时，顾客在 Confirm Order 步骤会看到 Test mode (demo.epay.bg): no real payment is taken.

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 签名。

已保存的密钥不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it. 仅在需要更改时输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。粘贴的密钥中的空格和换行会在保存时被删除。

付款通知（IPN）

通知用于告知您的店铺某个付款请求已被支付、被拒绝或已过期。Notification URL 字段显示的 URL 需要在 ePay.bg 商户资料中作为 URL for receiving notifications 填写，正式和 demo 均需如此。在 OpenCart 3 中其格式类似：https://your-store/index.php?route=extension/payment/wcp_epaybg_gateway/notify，在 OpenCart 4 中类似：https://your-store/index.php?route=extension/wcp_epaybg_gateway/payment/wcp_epaybg_gateway.notify，由您的 OpenCart 安装的店铺前台地址生成。请完全按设置中显示的样子复制该 URL。只有这些经过签名的通知才会使订单获得状态；顾客返回店铺并不构成对订单的付款。

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

没有有效校验和的通知会被拒绝，ePay.bg 会继续发送。校验和使用每个拥有密钥的模式的密钥进行检查，因此在您切换测试和正式模式之前发起的付款仍会被确认。付款必须在其请求所处的模式下到达；否则订单会进入 on-hold 状态。如果商户资料中没有通知 URL，订单将不会获得任何状态。

付款请求

Invoice Prefix：仅限数字（最多 10 位），放在 OpenCart 订单 ID 前面，组成 ePay.bg 发票号，例如 00001 + 123 = 00001123。同一 ePay.bg 账户上的不同店铺请使用不同的前缀。保存时会删除其他字符，并显示显示已保存前缀的警告。之后更改前缀是安全的：未完成的付款请求会通过为其保存的发票找到。默认：00001。

Expiration Time：未付款的付款请求在此时间之后过期；ePay.bg 会将其报告为已过期，订单不会获得任何状态。可选择 1、3、6、12、24、48 或 72 小时。时间以保加利亚时间发送，与店铺的时区无关。默认：24 小时。

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

订单

OpenCart 在 Confirm Order 步骤创建订单时不带状态（即缺失订单）。只有 ePay.bg 报告付款后，订单才会获得状态。付款被拒绝、过期或中途放弃，都会使订单保持无状态，顾客可以重新付款。下面的状态字段列出了您的 OpenCart 订单状态。

Order Status After Payment：付款成功后设置的状态。

Processing status：Default 和 Processing 对应的 OpenCart 状态。默认：Processing。

Completed status：Completed 对应的 OpenCart 状态。默认：Complete。

On Hold status：On Hold 以及需要人工审核的付款对应的 OpenCart 状态：付款请求之后订单金额或币种发生了变化、通知以另一模式到达，或者在付款到达前订单状态已被更改（例如已取消）。此类订单不会被标记为已付款；备注会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态并在此处选择。

高级

Logging：将付款请求和通知写入 OpenCart 日志文件夹（storage/logs）中的 epay_bp_debug.log.php。该文件无法通过网页打开，当大小达到 5 MB 时会移动到 epay_bp_debug.old.log.php。不记录密钥或银行卡数据。默认：关闭。即使关闭，错误也始终会被记录。

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

Delete Data on Uninstall：开启后，卸载扩展时会删除网关设置和日志。ePay.bg 付款记录和订单始终保留。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 ePay.bg）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to ePay.bg to pay with a bank card or your ePay.bg account. OpenCart 在此步骤创建订单，仍然不带状态。在 OpenCart 4 中，顾客使用 Payment method options 窗口中付款方式区块的 Choose 按钮选择付款方式，然后点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会以订单货币的订单金额发送一个经过签名的付款请求，并附带发票号和过期时间，将顾客带到 ePay.bg。付款在 ePay.bg 上显示为 Order 及订单号。在 ePay.bg 上，顾客使用银行卡或 ePay.bg 账户付款。

付款后，顾客返回您的店铺。只有在 ePay.bg 通过经过签名的通知确认付款后，订单才会被标记为已付款。随后订单会按照 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。如果通知已经到达，顾客会看到 OpenCart 订单成功页面。如果未到达，Payment confirmation 页面会显示 Thank you. Your payment is being confirmed by ePay.bg — your order is confirmed as soon as ePay.bg reports the payment.，并带有 Check again 和 Back to checkout 按钮。

如果顾客在 ePay.bg 上取消，会返回结账页面，并看到 The ePay.bg payment was cancelled. You can try again or choose another payment method. 如果 ePay.bg 已将请求报告为被拒绝或已过期，则消息为 The payment was not completed. You can try again or choose another payment method. 购物车会被保留。在 OpenCart 4 中，这些消息显示在结账页面上方。同一订单的新尝试会使用相同的发票号。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账订单，因此新的尝试会以新的付款请求支付同一订单。如果同一购物车中的另一订单已付款，顾客会被带到成功页面，并且不会开始新的付款。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单期间在未付款的情况下被关闭（例如您取消了它），顾客会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，下一次点击 Confirm Order 时将为购物车支付一个新订单。如果该订单已付款但购物车此后已更改（包括数量变化），顾客会被带回结账页面，下一次点击 Confirm Order 时将以新订单支付新购物车。已付款的订单绝不会对不同的购物车显示为已付款。

如果订单无法通过 ePay.bg 付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 ePay.bg payments are temporarily unavailable. Please choose another payment method.，或者提示 ePay.bg 不接受该订单货币的付款。

由于 OpenCart 3 允许付款扩展的请求通过，并且在 OpenCart 4 中该扩展会为此添加一个启动动作，因此即使店铺处于维护模式，通知也能正常工作。即使您关闭了付款方式，对已开始付款的通知仍会被接受。

该扩展仅支持在 ePay.bg 上进行的一次性付款。它不支持从 OpenCart 退款、保存银行卡、订阅或定期付款，也不支持 EasyPay 或 B-Pay 现金付款代码。

订单

订单状态

No status (missing order)：顾客已被转到 ePay.bg 但尚未付款，通知尚未到达，或 ePay.bg 已将请求报告为被拒绝或已过期。在 Sales > Orders 中，只有将 Order Status 筛选条件设为 Missing Orders，才会显示此类订单。

Processing, Completed 或 On Hold status：付款已确认。状态取决于 Order Status After Payment。备注中会显示发票号、付款日期、STAN 和 BORICA 代码。

付款后的 On Hold status：付款已到达，但与订单目前的状态不符：付款请求之后订单金额或币种发生了变化，通知以与请求不同的模式（测试或正式）到达，或订单的付款方式已不再是 ePay.bg。该付款不会被记录为已付款。如果您已为订单设置了其他状态（例如已取消），也会发生同样的情况。备注会说明原因。请在 ePay.bg 商户面板中核实付款，然后手动处理或退款订单。

如果为已付款的订单又收到一笔付款，状态不会改变，备注会提醒您在 ePay.bg 商户面板中检查是否重复付款。如果顾客为同一购物车支付了两笔订单，第二笔会收到可能重复付款的备注。延迟到达的拒绝或过期通知绝不会改变已付款的订单；已有状态的订单只会收到备注。

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

VibeFox ePay.bg Gateway 标签页

在 Sales > Orders 中打开一个通过 ePay.bg 付款的订单。在订单页面底部，与 History 和 Additional 并列的 VibeFox ePay.bg Gateway 标签页会显示发票、环境（测试或正式，测试付款会带有 Test mode 标签）、请求的金额和币种、付款请求的状态、通知结果、付款日期、STAN、BORICA 代码以及订单的 ePay.bg notes。该标签页为只读，仅向有权访问该扩展的用户显示。

退款

无法从 OpenCart 退款，因为 ePay.bg WEB API 没有退款接口。请在 ePay.bg 商户面板中退还付款，然后在 OpenCart 中手动更新订单状态。Sales > Returns 中的商品退货不会通过 ePay.bg 退还款项。

许可证密钥

该扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox ePay.bg Gateway 位于 Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > Edit 页面中，是设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺移除密钥）。其下方是 Product: opencart-payment-epaybg 一行和链接 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 账户中释放该名额。

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

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

故障排除

结账时不显示 ePay.bg：请检查许可证是否有效，Enable/Disable 是否开启，所选模式的 MIN 和密钥是否已设置，以及顾客是否以 BGN、EUR 或 USD 结账。缺少凭据时设置页面会显示警告。还要检查付款地址是否位于所选 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：订单只会从 ePay.bg 通知中获得状态。请检查您所用模式（demo 或正式）的 ePay.bg 商户资料中是否已按 Notification URL 中显示的内容准确填写通知 URL，并确认该模式的密钥正确。查看扩展页面上的 Log 字段；开启 Logging 可查看每一条通知。

通知返回 ERR=Not valid CHECKSUM：没有任何已保存的密钥与发送该通知的商户资料匹配。ePay.bg 会持续重试，因此密钥正确后订单将获得状态。

通知返回 ERR=Not configured：没有保存任何密钥。请输入。

通知对某张发票返回 STATUS=NO：该发票并非由此店铺开具，例如由同一 ePay.bg 账户上的另一店铺开具。请为每个店铺设置各自的 Invoice Prefix。

通知返回 STATUS=ERR：临时错误，例如同一时刻对同一订单收到两条通知，或无法设置订单状态。ePay.bg 会重新发送通知。原因记录在日志中。

通知 URL 显示 ERR=Method not allowed in the browser：这是正常现象。该 URL 只接受来自 ePay.bg 的请求。

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

顾客看到 This order has nothing to pay.：订单总额为零，因此没有需要发送到 ePay.bg 的内容。

订单在付款后处于 On Hold status：请阅读 VibeFox ePay.bg Gateway 标签页中的备注（参见订单状态），在 ePay.bg 商户面板中核实付款，然后处理订单或在那里退款。

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

对于开发人员：在付款表单发送到 ePay.bg 之前，扩展会触发 OpenCart 事件 epay_bp_form_fields，并附带表单字段和订单，例如用于使用直接银行卡付款页面（PAGE=credit_paydirect）；已签名的数据和校验和无法通过该事件修改。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox ePay.bg Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。在 OpenCart 4 中，该扩展的事件（结账消息）及其在维护模式下放行通知的启动动作也会被移除。如果 Delete Data on Uninstall 开启，其他网关设置（标题、描述、测试模式、MIN 和密钥、付款请求、付款后状态、日志记录）和日志也会被删除；如果关闭，则会保留，以便日后重新安装时使用。ePay.bg 付款记录始终会保留，因此在重新安装之前发起的付款仍会被确认。现有订单会保留其付款备注。

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

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