VibeFox ePay.bg for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块会拒绝在较旧的 PHP 版本上安装。

币种：保加利亚列弗（BGN）、欧元（EUR）或美元（USD）。购物车以其自身币种扣款，保留 2 位小数。对于其他币种的购物车，结账时会隐藏该付款方式。

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

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

安装

1. 进入后台，前往 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox ePay.bg Gateway，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（见许可证密钥）。

4. 输入测试和/或正式环境的 MIN 和密钥（参见“配置”）。

5. 将 Payment notifications (IPN) 部分显示的 URL 复制到 ePay.bg 商户资料中的 URL for receiving notifications 字段，演示和正式商户资料都要填写。否则不会创建订单。

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

安装时，模块会创建订单状态 ePay.bg payment on hold。PrestaShop 会为所有币种、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中加以限制。

配置

所有设置都在模块页面：Modules > Module Manager > VibeFox ePay.bg Gateway > Configure。每个 Save 按钮都会保存整个页面。在字段上方，如果店铺默认币种不是 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：启用测试模式。顾客会被转到 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 签名。

已保存的密钥不会再次显示。该字段保持为空并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。粘贴的密钥中的空格和换行会在保存时被删除。

Clear saved secret keys：勾选某个密钥并点击 Save 即可将其删除。空字段会保留已保存的值。

Payment notifications (IPN)

通知会告知您的店铺某个付款请求已付款、被拒绝或已过期。Notification URL 字段显示的 URL 需要在 ePay.bg 商户资料中作为 URL for receiving notifications 填写，正式和测试都需要。启用友好 URL 时，其形式为 https://your-shop/module/wcp_epaybg_gateway/notify，可能带有语言代码，如 /en/。请完全按照设置中显示的内容复制 URL。订单仅由这些已签名的通知创建；顾客返回店铺不会创建或支付订单。

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

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

Payment request

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：付款成功后设置的订单状态。

Advanced

Logging：将付款请求和通知写入模块文件夹中的 logs/epay_bp_debug.log.php。该文件无法通过网页打开。密钥和银行卡数据不会被记录。默认：关闭。即使关闭，错误也始终会被记录。

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

Delete Data on Uninstall：开启时，卸载模块会删除网关设置和日志。ePay.bg 付款记录、订单状态 ePay.bg payment on hold 以及订单始终保留。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 ePay.bg）并确认。顾客会看到 Redirecting to ePay.bg for payment...，随后被转到 ePay.bg，并收到以购物车币种按购物车总额生成的已签名付款请求，其中包含发票号和过期时间。在 ePay.bg 上，该付款显示为 Cart 和购物车编号。如果转跳没有开始，页面还提供一个 Pay via ePay.bg 按钮，以及一个 Cancel 按钮。在 ePay.bg 上，顾客使用银行卡或 ePay.bg 账户付款。此时尚不存在订单。

付款后，顾客返回您的店铺。只有在收到已签名的 ePay.bg 通知后才会创建订单。如果通知已经到达，顾客会看到标准的订单确认页面。如果尚未到达，Payment confirmation 页面会显示 Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. 并带有 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. 购物车会被保留。同一购物车的新尝试会使用相同的发票号。

如果购物车无法通过 ePay.bg 付款，顾客会停留在结账页面，并看到简短提示，例如 ePay.bg payments are temporarily unavailable. Please choose another payment method. 或提示 ePay.bg 不接受购物车币种的付款。

即使店铺处于维护模式，通知仍然有效，且不会被店铺的国家限制阻止。

模块仅接受 ePay.bg 上的一次性付款。不支持通过 PrestaShop 退款、保存银行卡、订阅或定期付款，也不支持 EasyPay 或 B-Pay 现金付款码。

订单

订单状态

No order yet：顾客已被转到 ePay.bg 但尚未付款，通知尚未到达，或 ePay.bg 报告该请求被拒绝或已过期。目前仅存在购物车。

Payment accepted, Delivered or ePay.bg payment on hold：付款已确认。状态遵循 Order Status After Payment。付款以 STAN 作为交易 ID 记录（若没有 STAN，则以发票号代替），备注中会显示发票号、付款日期、STAN 和 BORICA 代码。

ePay.bg payment on hold after payment：付款已到达，但与购物车当前的内容不符：购物车总额或币种在付款请求之后被修改，或通知来自与请求不同的模式（测试或正式）。该付款不会被记录为已付款。如果购物车已有未付款的订单（例如已取消的订单，或使用其他付款方式下的订单），也会出现同样的情况。备注会说明原因。请在 ePay.bg 商户面板中核实付款，然后手动处理或退款该订单。

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

ePay.bg 付款区块

订单页面会显示 ePay.bg payment 区块，包括发票、请求的金额和币种、通知结果、付款日期、STAN、BORICA 代码、测试付款的 Test mode 标记，以及订单的 ePay.bg notes。

退款

由于 ePay.bg WEB API 没有退款接口，因此无法通过 PrestaShop 退款。请在 ePay.bg 商户面板中对付款进行退款，并在 PrestaShop 中手动更新订单。

许可证密钥

本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox ePay.bg Gateway 是 Modules > Module Manager > VibeFox ePay.bg Gateway > Configure 页面中位于设置上方的第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有一行 Product: presta-payment-epaybg 和链接 Manage licenses and domains in your account，点击后将打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工才能更改密钥。区块中的文字遵循后台语言（包含英语和俄语）。

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

一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中同样适用。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 ePay.bg。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会被确认。

许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需配置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时未显示 ePay.bg：请检查许可证是否有效、Enable/Disable 是否开启、所选模式的 MIN 和密钥是否已设置，以及购物车币种是否为 BGN、EUR 或 USD。缺少凭据时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车币种、顾客所在国家和顾客群组。

付款已完成，但未创建订单：订单只会由 ePay.bg 通知创建。请检查您所用模式（演示或正式）的 ePay.bg 商户资料中是否填写了通知 URL，且与 Notification 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 的请求。

付款后订单处于 ePay.bg payment on hold 状态：请阅读 ePay.bg payment 区块中的备注（参见订单状态），在 ePay.bg 商户面板中核实付款，然后处理订单或在那里对付款进行退款。

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

对于开发者，readme 提到了钩子 actionEpayBpFormFields（即 WooCommerce 版本中的 epay_bp_form_fields 过滤器），例如可用于使用直接银行卡页面（PAGE=credit_paydirect）。

卸载

进入 Modules > Module Manager，打开 VibeFox ePay.bg Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，网关设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。ePay.bg 付款记录和订单状态 ePay.bg payment on hold 始终保留，因此重新安装之前发起的付款仍会被确认。现有订单会保留其付款备注和交易 ID。

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